pilotswarm-sdk 0.5.57 → 0.5.59

package/api/README.md

@@ -21,8 +21,14 @@ const api = new ApiClient({
 const session = await api.call("createSession", { model: "anthropic:claude-sonnet-4-6" });
 await api.call("sendMessage", { sessionId: session.sessionId, prompt: "hello" });
 const unsubscribe = api.subscribeSession(session.sessionId, (event) => console.log(event));
+const unsubscribeLive = api.subscribeLive(session.sessionId, "turn", (update) => console.log(update));
 ```
 
+`subscribeLive` carries ephemeral last-value topics such as in-progress turn
+text. It resubscribes automatically, ignores duplicate sequence values, and
+refetches a topic snapshot with `getLive` after a sequence gap. Live values
+are never part of the durable session event log.
+
 ## Modules
 
 - `src/protocol.js` — the **operations table**: every JSON operation's name,

package/api/index.d.ts

@@ -62,6 +62,23 @@ export interface ApiClientOptions {
     WebSocketImpl?: unknown;
 }
 
+/** Generic ephemeral topic delivery; never a durable replay event. */
+export type LiveUpdate = {
+    sessionId: string;
+    topic: string;
+    updatedAt?: string;
+} & ({ kind: "snapshot" | "patch"; seq: number; data: Record<string, unknown> }
+    | { kind: "signal"; seq?: number | null }
+    | { kind: "unavailable" });
+
+export interface LiveStateRow {
+    topic: string;
+    seq: number;
+    payload: Record<string, unknown>;
+    updatedBy: string;
+    updatedAt: string;
+}
+
 export declare class ApiClient {
     constructor(options: ApiClientOptions);
     apiUrl: string;
@@ -81,6 +98,7 @@ export declare class ApiClient {
     start(): Promise<void>;
     stop(): Promise<void>;
     subscribeSession(sessionId: string, handler: (event: unknown) => void, onResubscribe?: () => void): () => void;
+    subscribeLive(sessionId: string, topic: string, handler: (update: LiveUpdate) => void): () => void;
     subscribeLogs(handler: (entry: unknown) => void): () => void;
 }
 
@@ -97,12 +115,16 @@ export interface HttpApiTransportOptions extends ApiClientOptions {
     host?: HttpApiTransportHost;
 }
 
+export { AdminScope, ADMIN_SCOPE_POLICY_VERSION, ADMIN_SCOPES, loadAdminScope, validateAdminScope, adminCanAccessResource, adminCapabilities } from "./src/admin-scope.js";
+export * from "./src/admin-diagnostics.js";
+
 export declare class HttpApiTransport {
     constructor(options: HttpApiTransportOptions);
     api: ApiClient;
     bootstrap: any;
     start(): Promise<void>;
     stop(): Promise<void>;
+    getLive(sessionId: string, topics?: string[]): Promise<LiveStateRow[]>;
     [method: string]: any;
 }
 
@@ -134,14 +156,14 @@ export type SessionAccessClass =
 export declare const SESSION_VISIBILITY_VALUES: readonly string[];
 export declare function normalizeVisibility(value: unknown, fallback: string): string;
 export declare function systemSessionsReadable(env?: Record<string, string | undefined>): boolean;
-export declare function relationFor(snapshot: SessionAccessSnapshot | null, opts?: { isAdmin?: boolean }): "owner" | "admin" | "collaborator";
+export declare function relationFor(snapshot: SessionAccessSnapshot | null, opts?: { isAdmin?: boolean; adminScope?: import("./src/admin-scope.js").AdminScope }): "owner" | "admin" | "collaborator";
 export declare function evaluateSessionAccess(
     accessClass: SessionAccessClass,
     snapshot: SessionAccessSnapshot | null,
-    opts?: { isAdmin?: boolean; systemReadable?: boolean },
+    opts?: { isAdmin?: boolean; systemReadable?: boolean; adminScope?: import("./src/admin-scope.js").AdminScope },
 ): SessionAccessDecision;
 /** Archive reads are owner-or-admin ONLY — never a share. See proposal §15 A3. */
 export declare function evaluateArchiveAccess(
     snapshot: SessionAccessSnapshot | null,
-    opts?: { isAdmin?: boolean },
+    opts?: { isAdmin?: boolean; adminScope?: import("./src/admin-scope.js").AdminScope },
 ): SessionAccessDecision;

package/api/index.js

@@ -21,6 +21,8 @@ export {
     evaluateArchiveAccess,
 } from "./src/session-authz.js";
 export { ApiClient } from "./src/api-client.js";
+export { ADMIN_SCOPE_POLICY_VERSION, ADMIN_SCOPES, loadAdminScope, validateAdminScope, adminCanAccessResource, adminCapabilities } from "./src/admin-scope.js";
+export * from "./src/admin-diagnostics.js";
 export { createCanvasLiveMirror, jsonMergePatch } from "./src/canvas-live-mirror.js";
 export { HttpApiTransport } from "./src/http-api-transport.js";
 export {

package/api/src/admin-diagnostics.d.ts

@@ -0,0 +1,4 @@
+export function projectUserAccounting<T>(stats: T): T;
+export function projectFleetAccounting<T>(stats: T): T;
+export function projectAgentWorkerState<T>(row: T): T;
+export function projectWorker<T>(row: T): T;

package/api/src/admin-diagnostics.js

@@ -0,0 +1,45 @@
+/** Content-free operational projections. Use only for a restricted viewer. */
+export function projectUserAccounting(stats) {
+    return { ...stats, users: (stats.users || []).map((user) => ({
+        ...user, sessionIds: [],
+        byModel: (user.byModel || []).map((model) => ({ ...model, sessionIds: [] })),
+    })) };
+}
+
+export function projectFleetAccounting(stats) {
+    const groups = new Map();
+    for (const row of stats.byAgent || []) {
+        const key = row.model ?? null;
+        const group = groups.get(key) || { agentId: null, model: key };
+        for (const [field, value] of Object.entries(row)) {
+            if (typeof value === "number" && field !== "cacheHitRatio") group[field] = (group[field] || 0) + value;
+        }
+        group.cacheHitRatio = group.totalTokensInput > 0 ? group.totalTokensCacheRead / group.totalTokensInput : null;
+        groups.set(key, group);
+    }
+    return { ...stats, byAgent: [...groups.values()], contentRedacted: true };
+}
+
+export function projectAgentWorkerState(row) {
+    const installed = Object.values(row.installed || {});
+    return { workerNodeId: row.workerNodeId, epoch: row.epoch, updatedAt: row.updatedAt,
+        installed: {}, installedCount: installed.length,
+        errorCount: installed.filter((entry) => entry?.status === "error").length,
+        contentRedacted: true };
+}
+
+export function projectWorker(row) {
+    const health = {};
+    for (const field of ["uptimeS", "rssBytes", "heapUsedBytes", "eventLoopDelayP99Ms", "activeSessions"]) {
+        if (typeof row.health?.[field] === "number") health[field] = row.health[field];
+    }
+    for (const field of ["orchestrationSlots", "workerSlots"]) {
+        if (typeof row.health?.[field]?.total === "number") health[field] = { total: row.health[field].total };
+    }
+    const packages = row.state?.["agent-packages"] || {};
+    return { workerNodeId: row.workerNodeId, pool: row.pool, phase: row.phase,
+        registeredAt: row.registeredAt, updatedAt: row.updatedAt,
+        info: { sdkVersion: row.info?.sdkVersion, authz: row.info?.authz }, health,
+        state: { "agent-packages": projectAgentWorkerState({ ...packages, workerNodeId: row.workerNodeId }) },
+        contentRedacted: true };
+}

package/api/src/admin-scope.d.ts

@@ -0,0 +1,12 @@
+export type AdminScope = "unrestricted" | "cluster";
+export declare const ADMIN_SCOPE_POLICY_VERSION: number;
+export declare const ADMIN_SCOPES: readonly AdminScope[];
+export declare function loadAdminScope(env?: Record<string, string | undefined>): AdminScope;
+export declare function validateAdminScope(env: Record<string, string | undefined>, options?: { authenticationEnabled?: boolean }): AdminScope;
+export declare function adminCanAccessResource(isAdmin: boolean | undefined, adminScope?: AdminScope, isSystem?: boolean): boolean;
+export declare function adminCapabilities(isAdmin: boolean, adminScope?: AdminScope): {
+    clusterManagement: boolean;
+    fleetAccounting: boolean;
+    userResourceBypass: boolean;
+    systemSessionAdmin: boolean;
+};

package/api/src/admin-scope.js

@@ -0,0 +1,39 @@
+/** Deployment policy, independent of the authenticated admin role. */
+export const ADMIN_SCOPE_POLICY_VERSION = 1;
+export const ADMIN_SCOPES = Object.freeze(["unrestricted", "cluster"]);
+
+export function loadAdminScope(env = (typeof process !== "undefined" ? process.env : {})) {
+    const scope = String(env.AUTHZ_ADMIN_SCOPE ?? "unrestricted").trim().toLowerCase();
+    if (!ADMIN_SCOPES.includes(scope)) {
+        throw new Error("AUTHZ_ADMIN_SCOPE must be cluster or unrestricted.");
+    }
+    return scope;
+}
+
+/** Workers validate enforcement; the portal additionally validates its actual auth provider. */
+export function validateAdminScope(env, { authenticationEnabled } = {}) {
+    const scope = loadAdminScope(env);
+    if (scope === "cluster") {
+        if (!["1", "true", "yes", "on"].includes(String(env.AUTHZ_ENFORCE_OWNERSHIP ?? "").trim().toLowerCase())) {
+            throw new Error("AUTHZ_ADMIN_SCOPE=cluster requires AUTHZ_ENFORCE_OWNERSHIP=true.");
+        }
+        if (authenticationEnabled === false) {
+            throw new Error("AUTHZ_ADMIN_SCOPE=cluster requires authentication.");
+        }
+    }
+    return scope;
+}
+
+/** System-target access is deliberately unchanged in phase 1. */
+export function adminCanAccessResource(isAdmin, adminScope = "unrestricted", isSystem = false) {
+    return Boolean(isAdmin && (adminScope === "unrestricted" || isSystem));
+}
+
+export function adminCapabilities(isAdmin, adminScope = "unrestricted") {
+    return {
+        clusterManagement: Boolean(isAdmin),
+        fleetAccounting: Boolean(isAdmin),
+        userResourceBypass: adminCanAccessResource(isAdmin, adminScope),
+        systemSessionAdmin: Boolean(isAdmin),
+    };
+}

package/api/src/api-client.js

@@ -1,4 +1,5 @@
 import { API_PREFIX, ApiError, WS_PATH, artifactDownloadPath, buildOperationRequest } from "./protocol.js";
+import { jsonMergePatch } from "./canvas-live-mirror.js";
 
 const RECONNECT_DELAY_MS = 1500;
 
@@ -66,6 +67,11 @@ export class ApiClient {
         this.sessionResubscribeHandlers = new Map();
         this.logSubscribers = new Set();
         this.canvasSubscribers = new Map();
+        this.liveSubscribers = new Map();
+        this.liveSequences = new Map();
+        this.liveRefetches = new Map();
+        this.liveValues = new Map();
+        this.liveRefetchTargets = new Map();
     }
 
     // ── HTTP ────────────────────────────────────────────────────────────
@@ -212,13 +218,22 @@ export class ApiClient {
         this.socket = null;
         this.socketOpenPromise = null;
         this.sessionSubscribers.clear();
+        this.sessionResubscribeHandlers.clear();
         this.logSubscribers.clear();
         this.canvasSubscribers.clear();
+        this.liveSubscribers.clear();
+        this.liveSequences.clear();
+        this.liveRefetches.clear();
+        this.liveValues.clear();
+        this.liveRefetchTargets.clear();
     }
 
     scheduleReconnect() {
         if (this.stopped || this.reconnectTimer) return;
-        if (this.sessionSubscribers.size === 0 && this.logSubscribers.size === 0) return;
+        if (this.sessionSubscribers.size === 0
+            && this.logSubscribers.size === 0
+            && this.canvasSubscribers.size === 0
+            && this.liveSubscribers.size === 0) return;
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             this.ensureSocket().catch(() => {});
@@ -262,6 +277,24 @@ export class ApiClient {
             socket.addEventListener("message", (event) => {
                 try {
                     const message = JSON.parse(String(event.data || ""));
+                    if (message.type === "error" && message.code === "ACCESS_REVOKED" && message.sessionId) {
+                        for (const key of this.liveValues.keys()) {
+                            if (key.startsWith(`${message.sessionId}\u0000`)) this.liveValues.delete(key);
+                        }
+                        for (const key of this.liveSubscribers.keys()) {
+                            const [sessionId, topic] = key.split("\u0000");
+                            if (sessionId !== message.sessionId) continue;
+                            // Use the normal invalidation path: besides the
+                            // retained value it invalidates an in-flight gap
+                            // fetch, so its older authorized reply cannot
+                            // repopulate a revoked live-only subscription.
+                            void this.handleLiveMessage({ kind: "unavailable", sessionId, topic, accessRevoked: true });
+                        }
+                        for (const handler of this.sessionSubscribers.get(message.sessionId) || []) {
+                            handler({ eventType: "session.access_revoked", sessionId: message.sessionId });
+                        }
+                        return;
+                    }
                     if (message.type === "sessionEvent") {
                         const handlers = this.sessionSubscribers.get(message.sessionId);
                         if (handlers) {
@@ -280,6 +313,10 @@ export class ApiClient {
                         }
                         return;
                     }
+                    if (message.type === "live") {
+                        void this.handleLiveMessage(message);
+                        return;
+                    }
                     // A canvas-scope error (plane unavailable, authz change,
                     // server rollback) releases the mirror's takeover of that
                     // session — otherwise legacy events would stay suppressed
@@ -291,12 +328,25 @@ export class ApiClient {
                             for (const handler of handlers) handler({ kind: "unavailable", sessionId: message.sessionId });
                         }
                     }
+                    if (message.type === "error" && message.scope === "live" && message.sessionId) {
+                        for (const key of this.liveSubscribers.keys()) {
+                            if (!key.startsWith(`${message.sessionId}\u0000`)) continue;
+                            void this.handleLiveMessage({ kind: "unavailable", sessionId: message.sessionId, topic: key.split("\u0000")[1] });
+                        }
+                    }
                 } catch {}
             });
 
             socket.addEventListener("close", (event) => {
                 this.socket = null;
                 this.socketOpenPromise = null;
+                for (const [key, handlers] of this.liveSubscribers) {
+                    const [sessionId, topic] = key.split("\u0000");
+                    for (const handler of handlers) {
+                        try { handler({ kind: "unavailable", sessionId, topic }); } catch {}
+                    }
+                }
+                this.liveValues.clear();
                 if (event.code === 4401) {
                     this.onUnauthorized();
                     return;
@@ -342,7 +392,114 @@ export class ApiClient {
         }
     }
 
+    async handleLiveMessage(message) {
+        const key = `${message.sessionId}\u0000${message.topic}`;
+        const handlers = this.liveSubscribers.get(key);
+        if (!handlers || handlers.size === 0) return;
+        if (message.kind === "unavailable") {
+            this.liveSequences.delete(key);
+            this.liveValues.delete(key);
+            this.liveRefetches.delete(key);
+            this.liveRefetchTargets.delete(key);
+            for (const handler of handlers) { try { handler(message); } catch {} }
+            return;
+        }
+        if (message.kind === "signal") {
+            for (const handler of handlers) {
+                try { handler(message); } catch {}
+            }
+            return;
+        }
+
+        const seq = Number(message.seq);
+        if (!Number.isFinite(seq) || seq < 1) return;
+        const previous = this.liveSequences.get(key);
+        if (previous != null && seq === previous) return;
+        if (message.kind === "snapshot" && previous != null && seq < previous) return;
+
+        // A patch is meaningful only against its immediate predecessor. The
+        // subscribe burst is a snapshot, so no predecessor means a missed
+        // burst too. Collapse concurrent gaps into one authoritative read.
+        if (message.kind === "patch" && (previous == null || seq !== previous + 1)) {
+            if (seq > Number(this.liveRefetchTargets.get(key)?.seq || 0)) {
+                this.liveRefetchTargets.set(key, message);
+            }
+            if (!this.liveRefetches.has(key)) {
+                const allowSequenceReset = previous != null && seq < previous;
+                const refetch = this.call("getLive", {
+                    sessionId: message.sessionId,
+                    topics: [message.topic],
+                }).then((rows) => {
+                    const row = (rows || []).find((candidate) => candidate?.topic === message.topic);
+                    const currentHandlers = this.liveSubscribers.get(key);
+                    // The last subscriber may have left and a new subscription
+                    // for the same key may already exist. Do not let the old
+                    // request inject its snapshot into that new subscription.
+                    if (!row || currentHandlers !== handlers || currentHandlers.size === 0
+                        || this.liveRefetches.get(key) !== refetch) return;
+                    const snapshotSeq = Number(row.seq);
+                    if (!Number.isFinite(snapshotSeq) || snapshotSeq < 1) return;
+                    const seen = this.liveSequences.get(key);
+                    if (seen != null && (
+                        (!allowSequenceReset && snapshotSeq <= seen)
+                        || (allowSequenceReset && (snapshotSeq === seen || (snapshotSeq < seen && seen !== previous)))
+                    )) return;
+                    this.liveSequences.set(key, snapshotSeq);
+                    const snapshot = {
+                        type: "live",
+                        sessionId: message.sessionId,
+                        topic: message.topic,
+                        seq: snapshotSeq,
+                        kind: "snapshot",
+                        data: row.payload || {},
+                        ...(row.updatedAt ? { updatedAt: row.updatedAt } : {}),
+                    };
+                    this.liveValues.set(key, snapshot);
+                    for (const handler of currentHandlers) {
+                        try { handler(snapshot); } catch {}
+                    }
+                }).catch(() => {
+                    // A later notification retries the authoritative read;
+                    // durable session events remain the product fallback.
+                }).finally(() => {
+                    // A replacement subscription can already have started a
+                    // newer refetch for this key; do not erase its guard.
+                    if (this.liveRefetches.get(key) === refetch) {
+                        this.liveRefetches.delete(key);
+                        const latest = this.liveRefetchTargets.get(key);
+                        this.liveRefetchTargets.delete(key);
+                        // A notification that arrived DURING the read may be
+                        // newer than its snapshot. Do not lose that last tick.
+                        if (latest && latest !== message && this.liveSubscribers.get(key) === handlers) {
+                            void this.handleLiveMessage(latest);
+                        }
+                    }
+                });
+                this.liveRefetches.set(key, refetch);
+            }
+            await this.liveRefetches.get(key);
+            return;
+        }
+
+        this.liveSequences.set(key, seq);
+        this.liveValues.set(key, {
+            ...message, kind: "snapshot",
+            data: message.kind === "patch"
+                ? jsonMergePatch(this.liveValues.get(key)?.data || {}, message.data || {})
+                : message.data,
+        });
+        for (const handler of handlers) {
+            try { handler(message); } catch {}
+        }
+    }
+
     resubscribeAll(isReconnect = false) {
+        if (isReconnect) {
+            this.liveSequences.clear();
+            this.liveValues.clear();
+            this.liveRefetches.clear();
+            this.liveRefetchTargets.clear();
+        }
         for (const sessionId of this.sessionSubscribers.keys()) {
             this.socketSend({ type: "subscribeSession", sessionId });
             // On a RECONNECT, live delivery resumes but events emitted during
@@ -363,6 +520,15 @@ export class ApiClient {
         for (const sessionId of this.canvasSubscribers.keys()) {
             this.socketSend({ type: "subscribeCanvas", sessionId });
         }
+        const liveBySession = new Map();
+        for (const key of this.liveSubscribers.keys()) {
+            const [sessionId, topic] = key.split("\u0000");
+            if (!liveBySession.has(sessionId)) liveBySession.set(sessionId, []);
+            liveBySession.get(sessionId).push(topic);
+        }
+        for (const [sessionId, topics] of liveBySession) {
+            this.socketSend({ type: "subscribeLive", sessionId, topics });
+        }
     }
 
     /**
@@ -432,6 +598,53 @@ export class ApiClient {
         };
     }
 
+    /** Subscribe to one generic live-plane topic for a session. */
+    subscribeLive(sessionId, topic, handler) {
+        const normalizedSessionId = String(sessionId || "").trim();
+        const normalizedTopic = String(topic || "").trim();
+        if (!normalizedSessionId || !/^[a-z][a-z0-9_.:-]{0,63}$/.test(normalizedTopic)) {
+            throw new Error("subscribeLive requires a session id and valid topic");
+        }
+        const key = `${normalizedSessionId}\u0000${normalizedTopic}`;
+        const alreadySubscribed = this.liveSubscribers.has(key);
+        if (!alreadySubscribed && [...this.liveSubscribers.keys()].filter((candidate) => candidate.startsWith(`${normalizedSessionId}\u0000`)).length >= 16) {
+            throw new Error("At most 16 live topics per session are supported");
+        }
+        if (!this.liveSubscribers.has(key)) this.liveSubscribers.set(key, new Set());
+        const handlers = this.liveSubscribers.get(key);
+        handlers.add(handler);
+        const topics = [];
+        for (const candidate of this.liveSubscribers.keys()) {
+            const [sid, liveTopic] = candidate.split("\u0000");
+            if (sid === normalizedSessionId) topics.push(liveTopic);
+        }
+        if (!alreadySubscribed) this.announceSubscription({ type: "subscribeLive", sessionId: normalizedSessionId, topics });
+        else if (this.liveValues.has(key)) {
+            try { handler(this.liveValues.get(key)); } catch {}
+        }
+        let active = true;
+        return () => {
+            if (!active) return;
+            active = false;
+            handlers.delete(handler);
+            if (handlers.size > 0 || this.liveSubscribers.get(key) !== handlers) return;
+            this.liveSubscribers.delete(key);
+            this.liveSequences.delete(key);
+            this.liveRefetches.delete(key);
+            this.liveRefetchTargets.delete(key);
+            this.liveValues.delete(key);
+            const remaining = [];
+            for (const candidate of this.liveSubscribers.keys()) {
+                const [sid, liveTopic] = candidate.split("\u0000");
+                if (sid === normalizedSessionId) remaining.push(liveTopic);
+            }
+            this.socketSend({ type: "unsubscribeLive", sessionId: normalizedSessionId });
+            if (remaining.length > 0) {
+                this.socketSend({ type: "subscribeLive", sessionId: normalizedSessionId, topics: remaining });
+            }
+        };
+    }
+
     subscribeLogs(handler) {
         this.logSubscribers.add(handler);
         this.announceSubscription({ type: "subscribeLogs" });

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

@@ -105,7 +105,8 @@ export class HttpApiTransport {
     }
 
     getAuthContext() {
-        return this.bootstrap?.auth || {
+        if (this.bootstrap?.auth) return { ...this.bootstrap.auth, adminScope: this.bootstrap.authz?.adminScope ?? "unrestricted" };
+        return {
             principal: null,
             authorization: { allowed: false, role: null, reason: "Auth context unavailable", matchedGroups: [] },
         };
@@ -496,6 +497,10 @@ export class HttpApiTransport {
         return this.api.call("getCanvasLive", { sessionId });
     }
 
+    async getLive(sessionId, topics) {
+        return this.api.call("getLive", { sessionId, topics });
+    }
+
     // The canvas KV store (door 1 — signed-in browser).
     async readCanvasKv(sessionId, slot, query = {}) {
         return this.api.call("readCanvasKv", {
@@ -667,9 +672,23 @@ export class HttpApiTransport {
                 }
             }
         });
+        const unsubscribeLive = this.api.subscribeLive(sessionId, "turn", (message) => {
+            if (message?.kind === "signal") return;
+            const data = message?.kind === "unavailable" ? { phase: "idle" } : message?.data;
+            if (!data || typeof data !== "object") return;
+            handler({
+                eventType: "assistant.live_tick",
+                sessionId,
+                transient: true,
+                liveSeq: Number(message.seq) || 0,
+                liveUpdatedAt: message.updatedAt,
+                data,
+            });
+        });
         return () => {
             unsubscribeEvents();
             unsubscribeCanvas();
+            unsubscribeLive();
             const handlers = this._canvasEmitHandlers.get(sessionId);
             if (handlers) {
                 handlers.delete(handler);

package/api/src/protocol.js

@@ -41,8 +41,8 @@ export const API_VERSION = 1;
 export const WS_PATH = "/api/v1/ws";
 
 /** WebSocket message vocabulary (same as the legacy /portal-ws, minus theme). */
-export const WS_CLIENT_MESSAGES = ["subscribeSession", "unsubscribeSession", "subscribeLogs", "unsubscribeLogs"];
-export const WS_SERVER_MESSAGES = ["ready", "subscribedSession", "sessionEvent", "subscribedLogs", "logEntry", "error"];
+export const WS_CLIENT_MESSAGES = ["subscribeSession", "unsubscribeSession", "subscribeLive", "unsubscribeLive", "subscribeLogs", "unsubscribeLogs"];
+export const WS_SERVER_MESSAGES = ["ready", "subscribedSession", "sessionEvent", "subscribedLive", "live", "subscribedLogs", "logEntry", "error"];
 
 /** Error code used when an SDK web-mode method has no API equivalent. */
 export const WEB_MODE_UNSUPPORTED = "WEB_MODE_UNSUPPORTED";
@@ -114,6 +114,7 @@ export const OPERATIONS = [
     { 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: "getCanvasLive", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/canvas-live", params: { sessionId: path("sessionId") }, summary: "The canvas data plane's last-value rows: current doc pointer + latest merged tick per slot. Snapshot source for live canvas subscriptions; empty when the deployment predates the plane." },
+    { name: "getLive", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/live", params: { sessionId: path("sessionId"), topics: query("json") }, summary: "Current retained values from the ephemeral live plane, optionally filtered by topic." },
     // The canvas KV store (interactive-canvas-apps Part C). canvas:read and
     // canvas:write are their OWN access classes: both gate on session read
     // (a canvas reader may hold no session write), and whether a read-only

package/api/src/session-authz.d.ts

@@ -8,6 +8,8 @@
  * gate that always passes.
  */
 
+import type { AdminScope } from "./admin-scope.js";
+
 export interface SessionAccessSnapshot {
     rootSessionId?: string;
     isSystem: boolean;
@@ -42,19 +44,19 @@ export declare function systemSessionsReadable(env?: Record<string, string | und
 
 export declare function relationFor(
     snapshot: SessionAccessSnapshot | null,
-    opts?: { isAdmin?: boolean },
+    opts?: { isAdmin?: boolean; adminScope?: AdminScope },
 ): "owner" | "admin" | "collaborator";
 
 export declare function evaluateSessionAccess(
     accessClass: SessionAccessClass,
     snapshot: SessionAccessSnapshot | null,
-    opts?: { isAdmin?: boolean; systemReadable?: boolean },
+    opts?: { isAdmin?: boolean; systemReadable?: boolean; adminScope?: AdminScope },
 ): SessionAccessDecision;
 
 /** Archive reads are owner-or-admin ONLY — never a share. See proposal §15 A3. */
 export declare function evaluateArchiveAccess(
     snapshot: SessionAccessSnapshot | null,
-    opts?: { isAdmin?: boolean },
+    opts?: { isAdmin?: boolean; adminScope?: AdminScope },
 ): SessionAccessDecision;
 
 /** A sign-in role observation read from the users table. */

package/api/src/session-authz.js

@@ -1,3 +1,5 @@
+import { adminCanAccessResource } from "./admin-scope.js";
+
 /**
  * Session-tree access predicate — the ONE implementation, shared by every
  * surface that has to answer "may this principal touch this session?".
@@ -54,9 +56,9 @@ function ownerLabel(snapshot) {
  * The caller's relation to a session tree, recorded on message payloads and
  * shown to the agent in multi-writer sessions.
  */
-export function relationFor(snapshot, { isAdmin } = {}) {
+export function relationFor(snapshot, { isAdmin, adminScope = "unrestricted" } = {}) {
     if (snapshot?.viewerIsOwner) return "owner";
-    if (isAdmin) return "admin";
+    if (adminCanAccessResource(isAdmin, adminScope, snapshot?.isSystem)) return "admin";
     return "collaborator";
 }
 
@@ -68,14 +70,14 @@ export function relationFor(snapshot, { isAdmin } = {}) {
  * @param {{isAdmin?: boolean, systemReadable?: boolean}} [opts]
  * @returns {{allowed: boolean, notFound?: boolean, reason?: string, breakGlass?: boolean}}
  */
-export function evaluateSessionAccess(accessClass, snapshot, { isAdmin = false, systemReadable = true } = {}) {
+export function evaluateSessionAccess(accessClass, snapshot, { isAdmin = false, systemReadable = true, adminScope = "unrestricted" } = {}) {
     if (!snapshot) {
         // Missing/deleted session: let the underlying operation produce its
         // own not-found; nothing to protect.
         return { allowed: true };
     }
 
-    if (isAdmin) {
+    if (adminCanAccessResource(isAdmin, adminScope, snapshot.isSystem)) {
         // Admins pass everything; flag break-glass when this would have been
         // invisible to a plain user in the same position.
         const wouldBeInvisible = !snapshot.viewerIsOwner
@@ -120,7 +122,7 @@ export function evaluateSessionAccess(accessClass, snapshot, { isAdmin = false,
     // manage / destroy / share: owner only (admin handled above).
     return snapshot.viewerIsOwner
         ? { allowed: true }
-        : { allowed: false, reason: `Only the session owner (${ownerLabel(snapshot)}) or an admin can do this.` };
+        : { allowed: false, reason: `Only the session owner (${ownerLabel(snapshot)})${adminScope === "unrestricted" ? " or an admin" : ""} can do this.` };
 }
 
 /**
@@ -137,9 +139,9 @@ export function evaluateSessionAccess(accessClass, snapshot, { isAdmin = false,
  * @param {{isAdmin?: boolean}} [opts]
  * @returns {{allowed: boolean, notFound?: boolean, reason?: string, breakGlass?: boolean}}
  */
-export function evaluateArchiveAccess(snapshot, { isAdmin = false } = {}) {
+export function evaluateArchiveAccess(snapshot, { isAdmin = false, adminScope = "unrestricted" } = {}) {
     if (!snapshot) return { allowed: true };
-    if (isAdmin) {
+    if (adminCanAccessResource(isAdmin, adminScope, snapshot.isSystem)) {
         // Reading someone else's raw session state is exactly what the
         // authz_audit table calls a break-glass read.
         return { allowed: true, breakGlass: !snapshot.viewerIsOwner };
@@ -149,7 +151,7 @@ export function evaluateArchiveAccess(snapshot, { isAdmin = false } = {}) {
         return {
             allowed: false,
             reason:
-                "Session archives are available to the session owner and administrators only. "
+                (adminScope === "cluster" ? "Session archives are available to the session owner only. " : "Session archives are available to the session owner and administrators only. ")
                 + "A share grants the conversation, not the raw session state behind it.",
         };
     }