pilotswarm-sdk 0.5.13 → 0.5.14

package/api/src/api-client.js

@@ -74,7 +74,7 @@ export class ApiClient {
         return headers;
     }
 
-    async request(method, pathWithQuery, { body, headers } = {}) {
+    async request(method, pathWithQuery, { body, headers, authProbe = false } = {}) {
         const requestHeaders = await this.authHeaders(headers || {});
         if (body !== undefined && !requestHeaders["content-type"]) {
             requestHeaders["content-type"] = "application/json";
@@ -90,7 +90,11 @@ export class ApiClient {
         }
         if (response.status === 403) {
             const error = await readErrorEnvelope(response);
-            this.onForbidden(error.message || "Forbidden");
+            // Only an ADMISSION probe (/auth/me, /bootstrap) flips the whole
+            // app to the "access denied" gate. A per-operation 403 (e.g. a
+            // non-owner tries to rename) is a normal authz denial — throw it so
+            // the caller surfaces it inline, don't sign the user out of the app.
+            if (authProbe) this.onForbidden(error.message || "Forbidden");
             throw error;
         }
         if (!response.ok) {
@@ -131,11 +135,11 @@ export class ApiClient {
     }
 
     async getAuthContext() {
-        return this.request("GET", `${API_PREFIX}/auth/me`);
+        return this.request("GET", `${API_PREFIX}/auth/me`, { authProbe: true });
     }
 
     async getBootstrap() {
-        return this.request("GET", `${API_PREFIX}/bootstrap`);
+        return this.request("GET", `${API_PREFIX}/bootstrap`, { authProbe: true });
     }
 
     /** Raw artifact download; returns the Response for streaming/blob use. */
@@ -150,9 +154,9 @@ export class ApiClient {
             throw await readErrorEnvelope(response);
         }
         if (response.status === 403) {
-            const error = await readErrorEnvelope(response);
-            this.onForbidden(error.message || "Forbidden");
-            throw error;
+            // Per-artifact denial (no access to this session) — surface inline,
+            // don't flip the whole app to the admission gate.
+            throw await readErrorEnvelope(response);
         }
         if (!response.ok) throw await readErrorEnvelope(response);
         return response;

package/api/src/http-api-transport.js

@@ -89,6 +89,35 @@ export class HttpApiTransport {
         return this.api.call("getSession", { sessionId });
     }
 
+    // ── Session sharing / access (security model) ────────────────────────
+    async getSessionAccess(sessionId) {
+        return this.api.call("getSessionAccess", { sessionId });
+    }
+
+    async setSessionVisibility(sessionId, visibility) {
+        return this.api.call("setSessionVisibility", { sessionId, visibility });
+    }
+
+    async grantSessionShare(sessionId, user, access) {
+        return this.api.call("grantSessionShare", { sessionId, user, access });
+    }
+
+    async revokeSessionShare(sessionId, user) {
+        return this.api.call("revokeSessionShare", { sessionId, user });
+    }
+
+    async listSessionShares(sessionId) {
+        return this.api.call("listSessionShares", { sessionId });
+    }
+
+    async listKnownUsers(opts = {}) {
+        return this.api.call("listKnownUsers", { limit: opts?.limit });
+    }
+
+    async listAuthzAudit(opts = {}) {
+        return this.api.call("listAuthzAudit", { limit: opts?.limit, sessionId: opts?.sessionId });
+    }
+
     async createSession(options = {}) {
         return this.api.call("createSession", options);
     }

package/api/src/protocol.js

@@ -14,6 +14,24 @@
  *   - "body"  — JSON request body field
  * Param types: "string" (default) | "number" | "boolean" | "json".
  * "json" query params carry JSON-encoded values (e.g. the paging cursor).
+ *
+ * Access classification (`access`) — REQUIRED on every operation; the portal
+ * runtime enforces it at dispatch (docs/proposals/user-admin-security-model.md):
+ *   - "authed"          admission gate only (any admitted caller)
+ *   - "session:list"    viewer-scoped listing (non-admins see their visible set)
+ *   - "session:create"  create (still subject to session-creation policy)
+ *   - "session:read"    requires read access to the session's tree root
+ *   - "session:write"   requires write access (owner, shared_write, write grant)
+ *   - "session:manage"  owner or admin
+ *   - "session:destroy" owner or admin
+ *   - "session:share"   owner or admin (visibility + share grants)
+ *   - "group:list"      owner-scoped group listing for non-admins
+ *   - "group:manage"    group owner or admin
+ *   - "facts:read"|"facts:write"  facts data-plane (role/session-scoped)
+ *   - "fleet:read"      admin-only observability
+ *   - "fleet:admin"     Tier-2 operational surface (admin)
+ * Ops whose session resource rides a non-standard param name declare
+ * `sessionParam` (e.g. listChildOutcomes → parentSessionId).
  */
 
 export const API_PREFIX = "/api/v1";
@@ -44,123 +62,132 @@ const body = () => ({ in: "body" });
  */
 export const OPERATIONS = [
     // ── Sessions (client surface) ───────────────────────────────────────
-    { name: "listSessions", method: "GET", path: "/sessions", summary: "List session summaries." },
-    { name: "createSession", method: "POST", path: "/sessions", params: { model: body(), reasoningEffort: body(), contextTier: body(), groupId: body() }, summary: "Create a session. Owner is the authenticated principal." },
-    { name: "createSessionForAgent", method: "POST", path: "/sessions/for-agent", params: { agentName: body(), model: body(), reasoningEffort: body(), contextTier: body(), title: body(), splash: body(), splashMobile: body(), initialPrompt: body(), groupId: body() }, summary: "Create a session bound to a named agent." },
-    { name: "getSession", method: "GET", path: "/sessions/:sessionId", params: { sessionId: path("sessionId") }, summary: "Get one session view (live orchestration status)." },
-    { name: "deleteSession", method: "DELETE", path: "/sessions/:sessionId", params: { sessionId: path("sessionId") }, summary: "Cancel and soft-delete a session." },
-    { name: "sendMessage", method: "POST", path: "/sessions/:sessionId/messages", params: { sessionId: path("sessionId"), prompt: body(), options: body() }, summary: "Send a prompt (options: { enqueueOnly?, clientMessageIds? })." },
-    { name: "sendAnswer", method: "POST", path: "/sessions/:sessionId/answers", params: { sessionId: path("sessionId"), answer: body() }, summary: "Answer a pending input-required question." },
-    { name: "sendSessionEvent", method: "POST", path: "/sessions/:sessionId/events", params: { sessionId: path("sessionId"), eventName: body(), data: body() }, summary: "Send a custom event into the session." },
-    { name: "cancelPendingMessage", method: "POST", path: "/sessions/:sessionId/cancel-pending", params: { sessionId: path("sessionId"), clientMessageIds: body() }, summary: "Cancel queued messages by client message ids." },
+    { name: "listSessions", access: "session:list", method: "GET", path: "/sessions", summary: "List session summaries." },
+    { name: "createSession", access: "session:create", method: "POST", path: "/sessions", params: { model: body(), reasoningEffort: body(), contextTier: body(), groupId: body(), visibility: body() }, summary: "Create a session. Owner is the authenticated principal; visibility defaults to the deployment default." },
+    { name: "createSessionForAgent", access: "session:create", method: "POST", path: "/sessions/for-agent", params: { agentName: body(), model: body(), reasoningEffort: body(), contextTier: body(), title: body(), splash: body(), splashMobile: body(), initialPrompt: body(), groupId: body(), visibility: body() }, summary: "Create a session bound to a named agent." },
+    { name: "getSession", access: "session:read", method: "GET", path: "/sessions/:sessionId", params: { sessionId: path("sessionId") }, summary: "Get one session view (live orchestration status)." },
+    { name: "deleteSession", access: "session:destroy", method: "DELETE", path: "/sessions/:sessionId", params: { sessionId: path("sessionId") }, summary: "Cancel and soft-delete a session." },
+    { name: "sendMessage", access: "session:write", method: "POST", path: "/sessions/:sessionId/messages", params: { sessionId: path("sessionId"), prompt: body(), options: body() }, summary: "Send a prompt (options: { enqueueOnly?, clientMessageIds? })." },
+    { name: "sendAnswer", access: "session:write", method: "POST", path: "/sessions/:sessionId/answers", params: { sessionId: path("sessionId"), answer: body() }, summary: "Answer a pending input-required question." },
+    { name: "sendSessionEvent", access: "session:write", method: "POST", path: "/sessions/:sessionId/events", params: { sessionId: path("sessionId"), eventName: body(), data: body() }, summary: "Send a custom event into the session." },
+    { name: "cancelPendingMessage", access: "session:write", method: "POST", path: "/sessions/:sessionId/cancel-pending", params: { sessionId: path("sessionId"), clientMessageIds: body() }, summary: "Cancel queued messages by client message ids." },
+
+    // ── Session sharing (security model) ────────────────────────────────
+    { name: "getSessionAccess", access: "session:read", method: "GET", path: "/sessions/:sessionId/access", params: { sessionId: path("sessionId") }, summary: "The caller's effective access to this session's tree: { visibility, relation, canWrite, canManage, owner }." },
+    { name: "setSessionVisibility", access: "session:share", method: "PUT", path: "/sessions/:sessionId/visibility", params: { sessionId: path("sessionId"), visibility: body() }, summary: "Set the tree's sharing level (private | shared_read | shared_write). Owner or admin." },
+    { name: "grantSessionShare", access: "session:share", method: "POST", path: "/sessions/:sessionId/shares", params: { sessionId: path("sessionId"), user: body(), access: body() }, summary: "Grant (or update) a targeted share ({ user: { provider, subject, email?, displayName? }, access: read|write }). Owner or admin." },
+    { name: "revokeSessionShare", access: "session:share", method: "POST", path: "/sessions/:sessionId/shares/revoke", params: { sessionId: path("sessionId"), user: body() }, summary: "Revoke a targeted share ({ user: { provider, subject } }). Owner or admin." },
+    { name: "listSessionShares", access: "session:share", method: "GET", path: "/sessions/:sessionId/shares", params: { sessionId: path("sessionId") }, summary: "List targeted shares on this session's tree. Owner or admin." },
+    { name: "listAuthzAudit", access: "authz:audit", method: "GET", path: "/management/authz-audit", params: { limit: query("number"), sessionId: query("string") }, summary: "Authz audit records, newest first. Admin fleet-wide; owners for their own sessions (sessionId required)." },
 
     // ── Session artifacts (JSON surface; binary download is a bespoke route) ──
-    { name: "listArtifacts", method: "GET", path: "/sessions/:sessionId/artifacts", params: { sessionId: path("sessionId") }, summary: "List artifacts for a session." },
-    { name: "getArtifactMetadata", method: "GET", path: "/sessions/:sessionId/artifacts/:filename/meta", params: { sessionId: path("sessionId"), filename: path("filename") }, summary: "Artifact metadata." },
-    { name: "downloadArtifact", method: "GET", path: "/sessions/:sessionId/artifacts/:filename/text", params: { sessionId: path("sessionId"), filename: path("filename") }, summary: "Artifact content as text (JSON envelope). Binary: GET …/download." },
-    { name: "uploadArtifact", method: "PUT", path: "/sessions/:sessionId/artifacts/:filename", params: { sessionId: path("sessionId"), filename: path("filename"), content: body(), contentType: body(), contentEncoding: body() }, summary: "Upload artifact content (base64 for binary; 2 MB JSON limit)." },
-    { name: "deleteArtifact", method: "DELETE", path: "/sessions/:sessionId/artifacts/:filename", params: { sessionId: path("sessionId"), filename: path("filename") }, summary: "Delete an artifact." },
+    { name: "listArtifacts", access: "session:read", method: "GET", path: "/sessions/:sessionId/artifacts", params: { sessionId: path("sessionId") }, summary: "List artifacts for a session." },
+    { name: "getArtifactMetadata", access: "session:read", method: "GET", path: "/sessions/:sessionId/artifacts/:filename/meta", params: { sessionId: path("sessionId"), filename: path("filename") }, summary: "Artifact metadata." },
+    { name: "downloadArtifact", access: "session:read", method: "GET", path: "/sessions/:sessionId/artifacts/:filename/text", params: { sessionId: path("sessionId"), filename: path("filename") }, summary: "Artifact content as text (JSON envelope). Binary: GET …/download." },
+    { name: "uploadArtifact", access: "session:write", method: "PUT", path: "/sessions/:sessionId/artifacts/:filename", params: { sessionId: path("sessionId"), filename: path("filename"), content: body(), contentType: body(), contentEncoding: body() }, summary: "Upload artifact content (base64 for binary; 2 MB JSON limit)." },
+    { name: "deleteArtifact", access: "session:manage", method: "DELETE", path: "/sessions/:sessionId/artifacts/:filename", params: { sessionId: path("sessionId"), filename: path("filename") }, summary: "Delete an artifact." },
 
     // ── Management: sessions ────────────────────────────────────────────
-    { name: "listSessionsPage", method: "GET", path: "/management/sessions", params: { limit: query("number"), cursor: query("json"), includeDeleted: query("boolean") }, summary: "Keyset-paginated session listing." },
-    { name: "renameSession", method: "PATCH", path: "/management/sessions/:sessionId", params: { sessionId: path("sessionId"), title: body() }, summary: "Rename a session." },
-    { name: "cancelSession", method: "POST", path: "/management/sessions/:sessionId/cancel", params: { sessionId: path("sessionId") }, summary: "Cancel a session." },
-    { name: "completeSession", method: "POST", path: "/management/sessions/:sessionId/complete", params: { sessionId: path("sessionId"), reason: body() }, summary: "Mark a session completed." },
-    { name: "stopSessionTurn", method: "POST", path: "/management/sessions/:sessionId/stop-turn", params: { sessionId: path("sessionId"), options: body() }, summary: "Abort the in-flight turn." },
-    { name: "setSessionModel", method: "POST", path: "/management/sessions/:sessionId/model", params: { sessionId: path("sessionId"), options: body() }, summary: "Switch the session model ({ model, reasoningEffort?, contextTier? })." },
-    { name: "restartSystemSession", method: "POST", path: "/management/sessions/:agentIdOrSessionId/restart-system", params: { agentIdOrSessionId: path("agentIdOrSessionId"), options: body() }, summary: "Restart a system session (complete | terminate | hard_delete)." },
-    { name: "exportExecutionHistory", method: "POST", path: "/management/sessions/:sessionId/export-execution-history", params: { sessionId: path("sessionId") }, summary: "Export execution history to an artifact; returns artifact meta." },
-    { name: "getSessionStatus", method: "GET", path: "/management/sessions/:sessionId/status", params: { sessionId: path("sessionId") }, summary: "Live custom status + orchestration status." },
-    { name: "waitForStatusChange", method: "GET", path: "/management/sessions/:sessionId/status/wait", params: { sessionId: path("sessionId"), afterVersion: query("number"), timeoutMs: query("number") }, summary: "Long-poll for a status version change (server-capped timeout)." },
-    { name: "getLatestResponse", method: "GET", path: "/management/sessions/:sessionId/latest-response", params: { sessionId: path("sessionId") }, summary: "Latest turn response payload, if any." },
-    { name: "getOrchestrationStats", method: "GET", path: "/management/sessions/:sessionId/orchestration-stats", params: { sessionId: path("sessionId") }, summary: "Orchestration runtime stats." },
-    { name: "getExecutionHistory", method: "GET", path: "/management/sessions/:sessionId/execution-history", params: { sessionId: path("sessionId"), executionId: query("number") }, summary: "Raw execution history events." },
-    { name: "getSessionEvents", method: "GET", path: "/management/sessions/:sessionId/events", params: { sessionId: path("sessionId"), afterSeq: query("number"), limit: query("number"), eventTypes: query("json") }, summary: "Session events after a sequence number (reconnect catch-up). Optional eventTypes (JSON string array) narrows to those event types server-side." },
-    { name: "getSessionEventsBefore", method: "GET", path: "/management/sessions/:sessionId/events-before", params: { sessionId: path("sessionId"), beforeSeq: query("number"), limit: query("number"), eventTypes: query("json") }, summary: "Older session events for history paging. Optional eventTypes (JSON string array) narrows to those event types server-side (chat transcript paging)." },
-    { name: "getSessionMetricSummary", method: "GET", path: "/management/sessions/:sessionId/metric-summary", params: { sessionId: path("sessionId") }, summary: "Per-session metric summary." },
-    { name: "getSessionTokensByModel", method: "GET", path: "/management/sessions/:sessionId/tokens-by-model", params: { sessionId: path("sessionId") }, summary: "Token totals grouped by model." },
-    { name: "getSessionTreeStats", method: "GET", path: "/management/sessions/:sessionId/tree-stats", params: { sessionId: path("sessionId") }, summary: "Stats rolled up across the spawn tree." },
-    { name: "getSessionSkillUsage", method: "GET", path: "/management/sessions/:sessionId/skill-usage", params: { sessionId: path("sessionId"), since: query("string") }, summary: "Skill usage for one session." },
-    { name: "getSessionTreeSkillUsage", method: "GET", path: "/management/sessions/:sessionId/tree-skill-usage", params: { sessionId: path("sessionId"), since: query("string") }, summary: "Skill usage across the spawn tree." },
-    { name: "getSessionFactsStats", method: "GET", path: "/management/sessions/:sessionId/facts-stats", params: { sessionId: path("sessionId") }, summary: "Facts stats for one session." },
-    { name: "getSessionTreeFactsStats", method: "GET", path: "/management/sessions/:sessionId/tree-facts-stats", params: { sessionId: path("sessionId") }, summary: "Facts stats across the spawn tree." },
+    { name: "listSessionsPage", access: "session:list", method: "GET", path: "/management/sessions", params: { limit: query("number"), cursor: query("json"), includeDeleted: query("boolean") }, summary: "Keyset-paginated session listing." },
+    { name: "renameSession", access: "session:manage", method: "PATCH", path: "/management/sessions/:sessionId", params: { sessionId: path("sessionId"), title: body() }, summary: "Rename a session." },
+    { name: "cancelSession", access: "session:manage", method: "POST", path: "/management/sessions/:sessionId/cancel", params: { sessionId: path("sessionId") }, summary: "Cancel a session." },
+    { name: "completeSession", access: "session:manage", method: "POST", path: "/management/sessions/:sessionId/complete", params: { sessionId: path("sessionId"), reason: body() }, summary: "Mark a session completed." },
+    { name: "stopSessionTurn", access: "session:write", method: "POST", path: "/management/sessions/:sessionId/stop-turn", params: { sessionId: path("sessionId"), options: body() }, summary: "Abort the in-flight turn." },
+    { name: "setSessionModel", access: "session:manage", method: "POST", path: "/management/sessions/:sessionId/model", params: { sessionId: path("sessionId"), options: body() }, summary: "Switch the session model ({ model, reasoningEffort?, contextTier? })." },
+    { name: "restartSystemSession", access: "fleet:admin", method: "POST", path: "/management/sessions/:agentIdOrSessionId/restart-system", params: { agentIdOrSessionId: path("agentIdOrSessionId"), options: body() }, summary: "Restart a system session (complete | terminate | hard_delete)." },
+    { name: "exportExecutionHistory", access: "session:manage", method: "POST", path: "/management/sessions/:sessionId/export-execution-history", params: { sessionId: path("sessionId") }, summary: "Export execution history to an artifact; returns artifact meta." },
+    { name: "getSessionStatus", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/status", params: { sessionId: path("sessionId") }, summary: "Live custom status + orchestration status." },
+    { name: "waitForStatusChange", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/status/wait", params: { sessionId: path("sessionId"), afterVersion: query("number"), timeoutMs: query("number") }, summary: "Long-poll for a status version change (server-capped timeout)." },
+    { name: "getLatestResponse", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/latest-response", params: { sessionId: path("sessionId") }, summary: "Latest turn response payload, if any." },
+    { name: "getOrchestrationStats", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/orchestration-stats", params: { sessionId: path("sessionId") }, summary: "Orchestration runtime stats." },
+    { name: "getExecutionHistory", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/execution-history", params: { sessionId: path("sessionId"), executionId: query("number") }, summary: "Raw execution history events." },
+    { name: "getSessionEvents", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/events", params: { sessionId: path("sessionId"), afterSeq: query("number"), limit: query("number"), eventTypes: query("json") }, summary: "Session events after a sequence number (reconnect catch-up). Optional eventTypes (JSON string array) narrows to those event types server-side." },
+    { name: "getSessionEventsBefore", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/events-before", params: { sessionId: path("sessionId"), beforeSeq: query("number"), limit: query("number"), eventTypes: query("json") }, summary: "Older session events for history paging. Optional eventTypes (JSON string array) narrows to those event types server-side (chat transcript paging)." },
+    { name: "getSessionMetricSummary", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/metric-summary", params: { sessionId: path("sessionId") }, summary: "Per-session metric summary." },
+    { name: "getSessionTokensByModel", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/tokens-by-model", params: { sessionId: path("sessionId") }, summary: "Token totals grouped by model." },
+    { name: "getSessionTreeStats", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/tree-stats", params: { sessionId: path("sessionId") }, summary: "Stats rolled up across the spawn tree." },
+    { name: "getSessionSkillUsage", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/skill-usage", params: { sessionId: path("sessionId"), since: query("string") }, summary: "Skill usage for one session." },
+    { name: "getSessionTreeSkillUsage", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/tree-skill-usage", params: { sessionId: path("sessionId"), since: query("string") }, summary: "Skill usage across the spawn tree." },
+    { name: "getSessionFactsStats", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/facts-stats", params: { sessionId: path("sessionId") }, summary: "Facts stats for one session." },
+    { name: "getSessionTreeFactsStats", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/tree-facts-stats", params: { sessionId: path("sessionId") }, summary: "Facts stats across the spawn tree." },
     // Retrieval / graph observability (tuner-grade diagnostics; read-only)
-    { name: "getSessionRetrievalUsage", method: "GET", path: "/management/sessions/:sessionId/retrieval-usage", params: { sessionId: path("sessionId"), since: query("string") }, summary: "Retrieval (facts/graph search) usage for one session." },
-    { name: "getSessionTreeRetrievalUsage", method: "GET", path: "/management/sessions/:sessionId/tree-retrieval-usage", params: { sessionId: path("sessionId"), since: query("string") }, summary: "Retrieval usage across the spawn tree." },
-    { name: "getSessionGraphNodeUsage", method: "GET", path: "/management/sessions/:sessionId/graph-node-usage", params: { sessionId: path("sessionId"), since: query("string"), limit: query("number"), nodeKeyLike: query("string"), kind: query("string") }, summary: "Graph node usage for one session." },
-    { name: "getSessionGraphEdgeSearchUsage", method: "GET", path: "/management/sessions/:sessionId/graph-edge-search-usage", params: { sessionId: path("sessionId"), since: query("string"), limit: query("number") }, summary: "Graph edge-search usage for one session." },
-    { name: "getSessionGraphSearches", method: "GET", path: "/management/sessions/:sessionId/graph-searches", params: { sessionId: path("sessionId"), limit: query("number") }, summary: "Recent graph search events for one session." },
-    { name: "listChildOutcomes", method: "GET", path: "/management/sessions/:parentSessionId/child-outcomes", params: { parentSessionId: path("parentSessionId") }, summary: "Child outcomes recorded under a parent session." },
-    { name: "getChildOutcome", method: "GET", path: "/management/child-outcomes/:childSessionId", params: { childSessionId: path("childSessionId") }, summary: "One child outcome." },
+    { name: "getSessionRetrievalUsage", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/retrieval-usage", params: { sessionId: path("sessionId"), since: query("string") }, summary: "Retrieval (facts/graph search) usage for one session." },
+    { name: "getSessionTreeRetrievalUsage", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/tree-retrieval-usage", params: { sessionId: path("sessionId"), since: query("string") }, summary: "Retrieval usage across the spawn tree." },
+    { name: "getSessionGraphNodeUsage", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/graph-node-usage", params: { sessionId: path("sessionId"), since: query("string"), limit: query("number"), nodeKeyLike: query("string"), kind: query("string") }, summary: "Graph node usage for one session." },
+    { name: "getSessionGraphEdgeSearchUsage", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/graph-edge-search-usage", params: { sessionId: path("sessionId"), since: query("string"), limit: query("number") }, summary: "Graph edge-search usage for one session." },
+    { name: "getSessionGraphSearches", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/graph-searches", params: { sessionId: path("sessionId"), limit: query("number") }, summary: "Recent graph search events for one session." },
+    { name: "listChildOutcomes", access: "session:read", sessionParam: "parentSessionId", method: "GET", path: "/management/sessions/:parentSessionId/child-outcomes", params: { parentSessionId: path("parentSessionId") }, summary: "Child outcomes recorded under a parent session." },
+    { name: "getChildOutcome", access: "session:read", sessionParam: "childSessionId", method: "GET", path: "/management/child-outcomes/:childSessionId", params: { childSessionId: path("childSessionId") }, summary: "One child outcome." },
 
     // ── Management: session groups ──────────────────────────────────────
-    { name: "listSessionGroups", method: "GET", path: "/management/session-groups", summary: "List session groups." },
-    { name: "createSessionGroup", method: "POST", path: "/management/session-groups", params: { input: body() }, summary: "Create a session group." },
-    { name: "updateSessionGroup", method: "PATCH", path: "/management/session-groups/:groupId", params: { groupId: path("groupId"), patch: body() }, summary: "Update group title/description." },
-    { name: "deleteSessionGroup", method: "DELETE", path: "/management/session-groups/:groupId", params: { groupId: path("groupId") }, summary: "Delete an empty session group." },
-    { name: "assignSessionsToGroup", method: "POST", path: "/management/session-groups/:groupId/assign", params: { groupId: path("groupId"), sessionIds: body() }, summary: "Assign sessions to a group." },
-    { name: "cancelSessionGroup", method: "POST", path: "/management/session-groups/:groupId/cancel", params: { groupId: path("groupId"), reason: body() }, summary: "Cancel all sessions in a group." },
-    { name: "completeSessionGroup", method: "POST", path: "/management/session-groups/:groupId/complete", params: { groupId: path("groupId"), options: body() }, summary: "Complete all sessions in a group." },
-    { name: "moveSessionsToGroup", method: "POST", path: "/management/session-groups/move", params: { groupId: body(), sessionIds: body() }, summary: "Move sessions between groups (groupId null = ungroup)." },
+    { name: "listSessionGroups", access: "group:list", method: "GET", path: "/management/session-groups", summary: "List session groups." },
+    { name: "createSessionGroup", access: "authed", method: "POST", path: "/management/session-groups", params: { input: body() }, summary: "Create a session group." },
+    { name: "updateSessionGroup", access: "group:manage", method: "PATCH", path: "/management/session-groups/:groupId", params: { groupId: path("groupId"), patch: body() }, summary: "Update group title/description." },
+    { name: "deleteSessionGroup", access: "group:manage", method: "DELETE", path: "/management/session-groups/:groupId", params: { groupId: path("groupId") }, summary: "Delete an empty session group." },
+    { name: "assignSessionsToGroup", access: "group:manage", method: "POST", path: "/management/session-groups/:groupId/assign", params: { groupId: path("groupId"), sessionIds: body() }, summary: "Assign sessions to a group." },
+    { name: "cancelSessionGroup", access: "group:manage", method: "POST", path: "/management/session-groups/:groupId/cancel", params: { groupId: path("groupId"), reason: body() }, summary: "Cancel all sessions in a group." },
+    { name: "completeSessionGroup", access: "group:manage", method: "POST", path: "/management/session-groups/:groupId/complete", params: { groupId: path("groupId"), options: body() }, summary: "Complete all sessions in a group." },
+    { name: "moveSessionsToGroup", access: "group:manage", method: "POST", path: "/management/session-groups/move", params: { groupId: body(), sessionIds: body() }, summary: "Move sessions between groups (groupId null = ungroup)." },
 
     // ── Management: fleet / users / facts / events ──────────────────────
-    { name: "getFleetStats", method: "GET", path: "/management/fleet/stats", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Fleet-wide stats." },
-    { name: "getFleetSkillUsage", method: "GET", path: "/management/fleet/skill-usage", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Fleet-wide skill usage." },
-    { name: "getFleetRetrievalUsage", method: "GET", path: "/management/fleet/retrieval-usage", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Fleet-wide retrieval usage." },
-    { name: "getFleetGraphNodeUsage", method: "GET", path: "/management/fleet/graph-node-usage", params: { since: query("string"), includeDeleted: query("boolean"), limit: query("number"), nodeKeyLike: query("string"), kind: query("string") }, summary: "Fleet-wide graph node usage." },
-    { name: "getUserStats", method: "GET", path: "/management/users/stats", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Per-user stats." },
-    { name: "getSharedFactsStats", method: "GET", path: "/management/facts/shared-stats", summary: "Shared facts stats." },
-    { name: "getFactsTombstoneStats", method: "GET", path: "/management/facts/tombstone-stats", params: { ttlSeconds: query("number") }, summary: "Soft-deleted facts awaiting reconciliation." },
-    { name: "getTopEventEmitters", method: "GET", path: "/management/events/top-emitters", params: { since: query("string"), limit: query("number") }, summary: "Noisiest event emitters since a date." },
-    { name: "pruneDeletedSummaries", method: "POST", path: "/management/summaries/prune-deleted", params: { olderThan: body() }, summary: "Prune summaries of deleted sessions." },
+    { name: "getFleetStats", access: "fleet:read", method: "GET", path: "/management/fleet/stats", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Fleet-wide stats." },
+    { name: "getFleetSkillUsage", access: "fleet:read", method: "GET", path: "/management/fleet/skill-usage", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Fleet-wide skill usage." },
+    { name: "getFleetRetrievalUsage", access: "fleet:read", method: "GET", path: "/management/fleet/retrieval-usage", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Fleet-wide retrieval usage." },
+    { name: "getFleetGraphNodeUsage", access: "fleet:read", method: "GET", path: "/management/fleet/graph-node-usage", params: { since: query("string"), includeDeleted: query("boolean"), limit: query("number"), nodeKeyLike: query("string"), kind: query("string") }, summary: "Fleet-wide graph node usage." },
+    { name: "getUserStats", access: "fleet:read", method: "GET", path: "/management/users/stats", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Per-user stats." },
+    { name: "listKnownUsers", access: "authed", method: "GET", path: "/management/users", params: { limit: query("number") }, summary: "Member directory (provider/subject/email/displayName) for share autocomplete; excludes synthetic principals." },
+    { name: "getSharedFactsStats", access: "fleet:read", method: "GET", path: "/management/facts/shared-stats", summary: "Shared facts stats." },
+    { name: "getFactsTombstoneStats", access: "fleet:read", method: "GET", path: "/management/facts/tombstone-stats", params: { ttlSeconds: query("number") }, summary: "Soft-deleted facts awaiting reconciliation." },
+    { name: "getTopEventEmitters", access: "fleet:read", method: "GET", path: "/management/events/top-emitters", params: { since: query("string"), limit: query("number") }, summary: "Noisiest event emitters since a date." },
+    { name: "pruneDeletedSummaries", access: "fleet:admin", method: "POST", path: "/management/summaries/prune-deleted", params: { olderThan: body() }, summary: "Prune summaries of deleted sessions." },
 
     // ── Facts data-plane (Tier 1: any admitted caller) ──────────────────
-    { name: "factsCapabilities", method: "GET", path: "/facts/capabilities", summary: "Store capabilities: { search, embedder, graph } — the remote isEnhancedFactStore/isGraphStore." },
-    { name: "readFacts", method: "GET", path: "/facts", params: { keyPattern: query("string"), scopeKeys: query("json"), tags: query("json"), sessionId: query("string"), agentId: query("string"), limit: query("number"), scope: query("string") }, summary: "Read facts (ReadFactsQuery params)." },
-    { name: "storeFact", method: "POST", path: "/facts", params: { input: body() }, summary: "Store a fact or facts (StoreFactInput | StoreFactInput[])." },
-    { name: "deleteFact", method: "POST", path: "/facts/delete", params: { input: body() }, summary: "Delete a fact / pattern (DeleteFactInput). POST because DELETE bodies are unreliable." },
-    { name: "searchFacts", method: "POST", path: "/facts/search", params: { query: body(), opts: body() }, summary: "Retrieval over facts (lexical | semantic | hybrid). [enhanced]" },
-    { name: "similarFacts", method: "POST", path: "/facts/similar", params: { scopeKey: body(), opts: body() }, summary: "Semantic nearest-neighbours of a known fact. [enhanced]" },
+    { name: "factsCapabilities", access: "authed", method: "GET", path: "/facts/capabilities", summary: "Store capabilities: { search, embedder, graph } — the remote isEnhancedFactStore/isGraphStore." },
+    { name: "readFacts", access: "facts:read", method: "GET", path: "/facts", params: { keyPattern: query("string"), scopeKeys: query("json"), tags: query("json"), sessionId: query("string"), agentId: query("string"), limit: query("number"), scope: query("string") }, summary: "Read facts (ReadFactsQuery params)." },
+    { name: "storeFact", access: "facts:write", method: "POST", path: "/facts", params: { input: body() }, summary: "Store a fact or facts (StoreFactInput | StoreFactInput[])." },
+    { name: "deleteFact", access: "facts:write", method: "POST", path: "/facts/delete", params: { input: body() }, summary: "Delete a fact / pattern (DeleteFactInput). POST because DELETE bodies are unreliable." },
+    { name: "searchFacts", access: "facts:read", method: "POST", path: "/facts/search", params: { query: body(), opts: body() }, summary: "Retrieval over facts (lexical | semantic | hybrid). [enhanced]" },
+    { name: "similarFacts", access: "facts:read", method: "POST", path: "/facts/similar", params: { scopeKey: body(), opts: body() }, summary: "Semantic nearest-neighbours of a known fact. [enhanced]" },
 
     // ── Facts operational (Tier 2: admin) ───────────────────────────────
-    { name: "getEmbedderStatus", method: "GET", path: "/facts/embedder", summary: "Durable embedder status. [enhanced]" },
-    { name: "startFactsEmbedder", method: "POST", path: "/facts/embedder/start", params: { intervalSeconds: body(), batch: body() }, admin: true, summary: "Start the durable embedder loop. [enhanced, admin]" },
-    { name: "stopFactsEmbedder", method: "POST", path: "/facts/embedder/stop", params: { reason: body() }, admin: true, summary: "Stop the durable embedder loop. [enhanced, admin]" },
-    { name: "forcePurgeFacts", method: "POST", path: "/facts/purge", params: { input: body() }, admin: true, summary: "Force-purge soft-deleted facts (ForcePurgeFactsInput). [admin]" },
+    { name: "getEmbedderStatus", access: "authed", method: "GET", path: "/facts/embedder", summary: "Durable embedder status. [enhanced]" },
+    { name: "startFactsEmbedder", access: "fleet:admin", method: "POST", path: "/facts/embedder/start", params: { intervalSeconds: body(), batch: body() }, admin: true, summary: "Start the durable embedder loop. [enhanced, admin]" },
+    { name: "stopFactsEmbedder", access: "fleet:admin", method: "POST", path: "/facts/embedder/stop", params: { reason: body() }, admin: true, summary: "Stop the durable embedder loop. [enhanced, admin]" },
+    { name: "forcePurgeFacts", access: "fleet:admin", method: "POST", path: "/facts/purge", params: { input: body() }, admin: true, summary: "Force-purge soft-deleted facts (ForcePurgeFactsInput). [admin]" },
 
     // ── Graph data-plane (Tier 1: any admitted caller) ──────────────────
-    { name: "searchGraphNodes", method: "POST", path: "/graph/nodes/search", params: { query: body() }, summary: "Search graph nodes (GraphNodeQuery)." },
-    { name: "searchGraphEdges", method: "POST", path: "/graph/edges/search", params: { query: body() }, summary: "Search graph edges (GraphEdgeQuery)." },
-    { name: "graphNeighbourhood", method: "POST", path: "/graph/neighbourhood", params: { nodeKey: body(), depth: body(), namespace: body() }, summary: "Expand a subgraph around a node." },
-    { name: "upsertGraphNode", method: "POST", path: "/graph/nodes", params: { input: body() }, summary: "Upsert a graph node (GraphNodeInput)." },
-    { name: "upsertGraphEdge", method: "POST", path: "/graph/edges", params: { input: body() }, summary: "Upsert a graph edge (GraphEdgeInput)." },
-    { name: "deleteGraphNode", method: "POST", path: "/graph/nodes/delete", params: { nodeKey: body(), namespace: body() }, summary: "Delete a graph node." },
-    { name: "deleteGraphEdge", method: "POST", path: "/graph/edges/delete", params: { fromKey: body(), toKey: body(), predicateKey: body(), namespace: body() }, summary: "Delete a graph edge." },
-    { name: "graphStats", method: "GET", path: "/graph/stats", params: { namespace: query("string") }, summary: "Graph node/edge counts." },
-    { name: "listGraphNamespaces", method: "GET", path: "/graph/namespaces", params: { prefix: query("string"), includeArchived: query("boolean"), includeDetails: query("boolean") }, summary: "List graph namespaces (corpora)." },
-    { name: "getGraphNamespace", method: "GET", path: "/graph/namespaces/:namespace", params: { namespace: path("namespace") }, summary: "One graph namespace descriptor." },
+    { name: "searchGraphNodes", access: "authed", method: "POST", path: "/graph/nodes/search", params: { query: body() }, summary: "Search graph nodes (GraphNodeQuery)." },
+    { name: "searchGraphEdges", access: "authed", method: "POST", path: "/graph/edges/search", params: { query: body() }, summary: "Search graph edges (GraphEdgeQuery)." },
+    { name: "graphNeighbourhood", access: "authed", method: "POST", path: "/graph/neighbourhood", params: { nodeKey: body(), depth: body(), namespace: body() }, summary: "Expand a subgraph around a node." },
+    { name: "upsertGraphNode", access: "authed", method: "POST", path: "/graph/nodes", params: { input: body() }, summary: "Upsert a graph node (GraphNodeInput)." },
+    { name: "upsertGraphEdge", access: "authed", method: "POST", path: "/graph/edges", params: { input: body() }, summary: "Upsert a graph edge (GraphEdgeInput)." },
+    { name: "deleteGraphNode", access: "authed", method: "POST", path: "/graph/nodes/delete", params: { nodeKey: body(), namespace: body() }, summary: "Delete a graph node." },
+    { name: "deleteGraphEdge", access: "authed", method: "POST", path: "/graph/edges/delete", params: { fromKey: body(), toKey: body(), predicateKey: body(), namespace: body() }, summary: "Delete a graph edge." },
+    { name: "graphStats", access: "authed", method: "GET", path: "/graph/stats", params: { namespace: query("string") }, summary: "Graph node/edge counts." },
+    { name: "listGraphNamespaces", access: "authed", method: "GET", path: "/graph/namespaces", params: { prefix: query("string"), includeArchived: query("boolean"), includeDetails: query("boolean") }, summary: "List graph namespaces (corpora)." },
+    { name: "getGraphNamespace", access: "authed", method: "GET", path: "/graph/namespaces/:namespace", params: { namespace: path("namespace") }, summary: "One graph namespace descriptor." },
 
     // ── Graph operational (Tier 2: admin) ───────────────────────────────
-    { name: "upsertGraphNamespace", method: "POST", path: "/graph/namespaces", params: { input: body() }, admin: true, summary: "Register/update a graph namespace. [admin]" },
-    { name: "deleteGraphNamespace", method: "DELETE", path: "/graph/namespaces/:namespace", params: { namespace: path("namespace") }, admin: true, summary: "Delete a graph namespace and its data. [admin]" },
+    { name: "upsertGraphNamespace", access: "fleet:admin", method: "POST", path: "/graph/namespaces", params: { input: body() }, admin: true, summary: "Register/update a graph namespace. [admin]" },
+    { name: "deleteGraphNamespace", access: "fleet:admin", method: "DELETE", path: "/graph/namespaces/:namespace", params: { namespace: path("namespace") }, admin: true, summary: "Delete a graph namespace and its data. [admin]" },
 
     // ── Models / agents / policy ────────────────────────────────────────
-    { name: "listModels", method: "GET", path: "/models", summary: "All available models." },
-    { name: "getModelsByProvider", method: "GET", path: "/models/by-provider", summary: "Models grouped by provider." },
-    { name: "getDefaultModel", method: "GET", path: "/models/default", summary: "The deployment default model." },
-    { name: "listCreatableAgents", method: "GET", path: "/agents", summary: "Agents sessions can be created for." },
-    { name: "getSessionCreationPolicy", method: "GET", path: "/session-creation-policy", summary: "Session creation policy." },
+    { name: "listModels", access: "authed", method: "GET", path: "/models", summary: "All available models." },
+    { name: "getModelsByProvider", access: "authed", method: "GET", path: "/models/by-provider", summary: "Models grouped by provider." },
+    { name: "getDefaultModel", access: "authed", method: "GET", path: "/models/default", summary: "The deployment default model." },
+    { name: "listCreatableAgents", access: "authed", method: "GET", path: "/agents", summary: "Agents sessions can be created for." },
+    { name: "getSessionCreationPolicy", access: "authed", method: "GET", path: "/session-creation-policy", summary: "Session creation policy." },
 
     // ── Current user profile ────────────────────────────────────────────
-    { name: "getCurrentUserProfile", method: "GET", path: "/me/profile", summary: "Profile of the authenticated principal." },
-    { name: "setCurrentUserProfileSettings", method: "PATCH", path: "/me/profile/settings", params: { settings: body() }, summary: "Replace profile settings." },
-    { name: "setCurrentUserGitHubCopilotKey", method: "PUT", path: "/me/github-copilot-key", params: { key: body() }, summary: "Set (or clear with null) the per-user GitHub Copilot key." },
-    { name: "setSystemGitHubCopilotKey", method: "PUT", path: "/admin/system-github-copilot-key", params: { key: body() }, admin: true, summary: "Set (or clear with null) the System user's GitHub Copilot key, used by ownerless system sessions. [admin]" },
-    { name: "getSystemGitHubCopilotKeyStatus", method: "GET", path: "/admin/system-github-copilot-key", admin: true, summary: "Whether a System GitHub Copilot key is configured and who last changed it. [admin]" },
+    { name: "getCurrentUserProfile", access: "authed", method: "GET", path: "/me/profile", summary: "Profile of the authenticated principal." },
+    { name: "setCurrentUserProfileSettings", access: "authed", method: "PATCH", path: "/me/profile/settings", params: { settings: body() }, summary: "Replace profile settings." },
+    { name: "setCurrentUserGitHubCopilotKey", access: "authed", method: "PUT", path: "/me/github-copilot-key", params: { key: body() }, summary: "Set (or clear with null) the per-user GitHub Copilot key." },
+    { name: "setSystemGitHubCopilotKey", access: "fleet:admin", method: "PUT", path: "/admin/system-github-copilot-key", params: { key: body() }, admin: true, summary: "Set (or clear with null) the System user's GitHub Copilot key, used by ownerless system sessions. [admin]" },
+    { name: "getSystemGitHubCopilotKeyStatus", access: "fleet:admin", method: "GET", path: "/admin/system-github-copilot-key", admin: true, summary: "Whether a System GitHub Copilot key is configured and who last changed it. [admin]" },
 
     // ── System ──────────────────────────────────────────────────────────
-    { name: "getLogConfig", method: "GET", path: "/system/log-config", summary: "Log tail availability." },
-    { name: "getWorkerCount", method: "GET", path: "/system/workers", summary: "Live worker count." },
+    { name: "getLogConfig", access: "authed", method: "GET", path: "/system/log-config", summary: "Log tail availability." },
+    { name: "getWorkerCount", access: "authed", method: "GET", path: "/system/workers", summary: "Live worker count." },
 ];
 
 const OPERATIONS_BY_NAME = new Map(OPERATIONS.map((op) => [op.name, op]));

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import type { PilotSwarmClientOptions, ManagedSessionConfig, PilotSwarmSessionInfo, UserInputHandler, SessionOwnerInfo } from "./types.js";
-import type { SessionCatalog, SessionEvent } from "./cms.js";
+import type { SessionCatalog, SessionEvent, SessionVisibility } from "./cms.js";
+import type { MessageSender } from "./message-sender.js";
 import { type PilotSwarmWebOptions } from "./web/api-connection.js";
 /**
  * PilotSwarmClient — pure client-side session handle.
@@ -52,6 +53,8 @@ export declare class PilotSwarmClient {
         owner?: SessionOwnerInfo | null;
         /** Optional visual session group assignment. */
         groupId?: string | null;
+        /** Sharing level for a new ROOT session (children resolve through their root). */
+        visibility?: SessionVisibility | null;
     }): Promise<PilotSwarmSession>;
     /**
      * Create a session bound to a named agent.
@@ -74,6 +77,7 @@ export declare class PilotSwarmClient {
         initialPrompt?: string;
         owner?: SessionOwnerInfo | null;
         groupId?: string | null;
+        visibility?: SessionVisibility | null;
     }): Promise<PilotSwarmSession>;
     /**
      * Create a system session (e.g. Sweeper Agent).
@@ -117,6 +121,7 @@ export declare class PilotSwarmClient {
         bootstrap?: boolean;
         requiredTool?: string;
         clientMessageIds?: string[];
+        sender?: MessageSender;
     }): Promise<string>;
     /** @internal */
     _getDuroxideClient(): any;
@@ -162,6 +167,7 @@ export declare class PilotSwarmSession {
         bootstrap?: boolean;
         requiredTool?: string;
         clientMessageIds?: string[];
+        sender?: MessageSender;
     }): Promise<void>;
     wait(timeout?: number, opts?: {
         signal?: AbortSignal;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -1,5 +1,6 @@
 import { RESPONSE_LATEST_KEY, } from "./types.js";
 import { DURABLE_SESSION_LATEST_VERSION, DURABLE_SESSION_ORCHESTRATION_NAME, } from "./orchestration-registry.js";
+import { normalizeMessageSender } from "./message-sender.js";
 import { resolveStorageConfig } from "./storage-config.js";
 import { getDuroxideStorageProvider, getRuntimeStorageProvider } from "./storage-providers.js";
 import { deriveStatusFromCmsAndRuntime, shouldSyncCompletedStatus, shouldSyncFailedStatus } from "./session-status.js";
@@ -118,6 +119,7 @@ export class PilotSwarmClient {
             parentSessionId: config?.parentSessionId,
             owner: config?.owner ?? null,
             groupId: config?.groupId ?? null,
+            visibility: config?.visibility ?? null,
         });
         // Track parentSessionId for sub-agent orchestration input
         if (config?.parentSessionId) {
@@ -159,6 +161,7 @@ export class PilotSwarmClient {
             promptLayering: { kind: "app-agent" },
             owner: opts?.owner ?? null,
             groupId: opts?.groupId ?? null,
+            visibility: opts?.visibility ?? null,
         });
         // Set agent metadata in CMS (agentId + prefixed title)
         const shortId = session.sessionId.slice(0, 8);
@@ -508,6 +511,10 @@ export class PilotSwarmClient {
             ...(opts?.clientMessageIds && opts.clientMessageIds.length > 0
                 ? { clientMessageIds: opts.clientMessageIds }
                 : {}),
+            ...(() => {
+                const sender = normalizeMessageSender(opts?.sender);
+                return sender ? { sender } : {};
+            })(),
         }));
         trace(`[client] enqueueEvent done (${Date.now() - enqueueAt}ms bootstrap=${opts?.bootstrap === true})`);
         trace("[client] ensureOrchestrationAndSend complete");