@nice-code/action 0.6.2 → 0.7.0

package/build/devtools/browser/index.js

@@ -5516,6 +5516,7 @@ var PREFS_KEY = "__nice-action-devtools-prefs";
 var DOCKED_HEIGHT_DEFAULT = 320;
 var DOCKED_WIDTH_DEFAULT = 420;
 var DETAIL_RATIO_DEFAULT = 0.5;
+var SANS_FONT2 = "ui-sans-serif, system-ui, sans-serif";
 var DOCK_POSITIONS = ["dock-bottom", "dock-top", "dock-left", "dock-right"];
 function isDockPosition(value) {
   return typeof value === "string" && DOCK_POSITIONS.includes(value);
@@ -5526,7 +5527,9 @@ function readPrefs(defaultPosition, initialOpen) {
     isOpen: initialOpen,
     dockedHeight: DOCKED_HEIGHT_DEFAULT,
     dockedWidth: DOCKED_WIDTH_DEFAULT,
-    detailRatio: DETAIL_RATIO_DEFAULT
+    detailRatio: DETAIL_RATIO_DEFAULT,
+    stayOnLatest: true,
+    followLatestOnSelect: true
   };
   try {
     if (typeof localStorage === "undefined")
@@ -5555,15 +5558,23 @@ function getHandlerKey(entry) {
     return "local";
   return `ext:${hop.transport ?? "ext"}`;
 }
+function entriesShareActionInput(a, b) {
+  if (a.actionId !== b.actionId || a.domain !== b.domain)
+    return false;
+  return a.inputHash != null && b.inputHash != null ? a.inputHash === b.inputHash : safeStringify(a.input, 0) === safeStringify(b.input, 0);
+}
 function canGroupWith(a, b) {
-  if (a.status === "running" || b.status === "running")
+  if (!entriesShareActionInput(a, b))
     return false;
   const handlerA = getHandlerKey(a);
   const handlerB = getHandlerKey(b);
   const handlerConflict = handlerA !== "none" && handlerB !== "none" && handlerA !== handlerB;
-  const inputMatch = a.inputHash != null && b.inputHash != null ? a.inputHash === b.inputHash : safeStringify(a.input, 0) === safeStringify(b.input, 0);
+  if (handlerConflict)
+    return false;
+  if (a.status === "running" || b.status === "running")
+    return true;
   const outputMatch = a.outputHash != null && b.outputHash != null ? a.outputHash === b.outputHash : true;
-  return a.actionId === b.actionId && a.domain === b.domain && a.status === b.status && !handlerConflict && inputMatch && outputMatch;
+  return a.status === b.status && outputMatch;
 }
 function groupEntries(entries) {
   const groups = [];
@@ -5596,7 +5607,7 @@ function NiceActionDevtools_Panel({
   useEffect4(() => core.subscribe(setEntries), [core]);
   const groups = useMemo3(() => {
     const byCuid = new Map(entries.map((e) => [e.cuid, e]));
-    const roots = entries.filter((e) => e.status !== "running" && (e.parentCuid == null || !byCuid.has(e.parentCuid)));
+    const roots = entries.filter((e) => e.parentCuid == null || !byCuid.has(e.parentCuid));
     return groupEntries(roots);
   }, [entries]);
   const childEntriesMap = useMemo3(() => {
@@ -5612,16 +5623,6 @@ function NiceActionDevtools_Panel({
     }
     return map;
   }, [entries]);
-  const handleGroupRowClick = (group) => {
-    const repCuid = group.representative.cuid;
-    const allInGroup = [group.representative, ...group.rest];
-    const selectedInGroup = allInGroup.find((e) => e.cuid === selectedCuid) ?? null;
-    if (selectedInGroup != null && selectedCuid !== repCuid) {
-      setSelectedCuid(repCuid);
-    } else {
-      setSelectedCuid(selectedCuid === repCuid ? null : repCuid);
-    }
-  };
   const setPrefs = (update) => {
     setPrefsRaw((prev) => ({ ...prev, ...update }));
   };
@@ -5629,10 +5630,34 @@ function NiceActionDevtools_Panel({
     const timer = setTimeout(() => writePrefs(prefs), 250);
     return () => clearTimeout(timer);
   }, [prefs]);
-  const { position, isOpen, dockedHeight, dockedWidth, detailRatio } = prefs;
+  const { position, isOpen, dockedHeight, dockedWidth, detailRatio, stayOnLatest, followLatestOnSelect } = prefs;
   const dockSide = getDockSide(position);
   const isHorizDock = dockSide === "top" || dockSide === "bottom";
   const dockedSize = isHorizDock ? dockedHeight : dockedWidth;
+  const latestCuid = groups.length > 0 ? groups[0].representative.cuid : null;
+  useEffect4(() => {
+    if (stayOnLatest && latestCuid != null)
+      setSelectedCuid(latestCuid);
+  }, [stayOnLatest, latestCuid]);
+  const applySelection = (next) => {
+    if (next != null && next === latestCuid && followLatestOnSelect) {
+      if (!stayOnLatest)
+        setPrefs({ stayOnLatest: true });
+    } else if (stayOnLatest) {
+      setPrefs({ stayOnLatest: false });
+    }
+    setSelectedCuid(next);
+  };
+  const handleGroupRowClick = (group) => {
+    const repCuid = group.representative.cuid;
+    const allInGroup = [group.representative, ...group.rest];
+    const selectedInGroup = allInGroup.find((e) => e.cuid === selectedCuid) ?? null;
+    if (selectedInGroup != null && selectedCuid !== repCuid) {
+      applySelection(repCuid);
+    } else {
+      applySelection(selectedCuid === repCuid ? null : repCuid);
+    }
+  };
   const selectedEntry = selectedCuid != null ? entries.find((e) => e.cuid === selectedCuid) : null;
   const runningCount = entries.filter((e) => e.status === "running").length;
   const dock = useMemo3(() => getDevtoolsDockCoordinator(), []);
@@ -5716,7 +5741,7 @@ function NiceActionDevtools_Panel({
     selectedCuid,
     onGroupClick: handleGroupRowClick,
     onSubClick: (cuid, isSelected) => {
-      setSelectedCuid(isSelected ? null : cuid);
+      applySelection(isSelected ? null : cuid);
     },
     childEntriesMap
   };
@@ -5748,18 +5773,35 @@ function NiceActionDevtools_Panel({
           minHeight: 0
         },
         children: [
-          /* @__PURE__ */ jsx23("div", {
+          /* @__PURE__ */ jsxs20("div", {
             style: {
               flexGrow: selectedEntry != null ? 1 - detailRatio : 1,
               flexShrink: 1,
               flexBasis: 0,
               minWidth: 0,
-              minHeight: 0
+              minHeight: 0,
+              display: "flex",
+              flexDirection: "column",
+              overflow: "hidden"
             },
-            children: /* @__PURE__ */ jsx23(ActionList, {
-              ...virtualListProps,
-              style: { width: "100%", height: "100%", overflowY: "auto" }
-            })
+            children: [
+              /* @__PURE__ */ jsx23(FollowToggles, {
+                stayOnLatest,
+                onStayOnLatestChange: (next) => setPrefs({ stayOnLatest: next }),
+                followLatestOnSelect,
+                onFollowLatestOnSelectChange: (next) => {
+                  if (next && latestCuid != null && selectedCuid === latestCuid && !stayOnLatest) {
+                    setPrefs({ followLatestOnSelect: next, stayOnLatest: true });
+                  } else {
+                    setPrefs({ followLatestOnSelect: next });
+                  }
+                }
+              }),
+              /* @__PURE__ */ jsx23(ActionList, {
+                ...virtualListProps,
+                style: { width: "100%", flex: 1, minHeight: 0, overflowY: "auto" }
+              })
+            ]
           }),
           selectedEntry != null && /* @__PURE__ */ jsxs20(Fragment11, {
             children: [
@@ -5799,6 +5841,82 @@ function NiceActionDevtools_Panel({
     ]
   });
 }
+function FollowToggles({
+  stayOnLatest,
+  onStayOnLatestChange,
+  followLatestOnSelect,
+  onFollowLatestOnSelectChange
+}) {
+  return /* @__PURE__ */ jsxs20("div", {
+    style: {
+      display: "flex",
+      flexDirection: "column",
+      flexShrink: 0,
+      paddingBottom: "3px",
+      background: DEVTOOL_SECTION_BACKGROUND,
+      borderBottom: `1px solid ${DEVTOOL_LIST_BASE_BACKGROUND}`
+    },
+    children: [
+      /* @__PURE__ */ jsx23(ToggleLabel, {
+        title: "Auto-select the most recent action so the detail pane keeps showing the latest as new actions land",
+        checked: stayOnLatest,
+        onChange: onStayOnLatestChange,
+        children: "Follow latest"
+      }),
+      /* @__PURE__ */ jsxs20("div", {
+        style: { display: "flex", alignItems: "center", paddingLeft: "12px", marginTop: "-4px" },
+        children: [
+          /* @__PURE__ */ jsx23("span", {
+            "aria-hidden": true,
+            style: {
+              color: DEVTOOL_COLOR_TEXT_MUTED,
+              fontFamily: SANS_FONT2,
+              fontSize: "10px",
+              lineHeight: 1
+            },
+            children: "└"
+          }),
+          /* @__PURE__ */ jsx23(ToggleLabel, {
+            title: "When you click the latest action, turn 'Follow latest' back on so the view resumes tracking new actions. Turn this off to pin exactly to the action you click instead.",
+            checked: followLatestOnSelect,
+            onChange: onFollowLatestOnSelectChange,
+            children: "clicking latest re-follows"
+          })
+        ]
+      })
+    ]
+  });
+}
+function ToggleLabel({
+  checked,
+  onChange,
+  title,
+  children
+}) {
+  return /* @__PURE__ */ jsxs20("label", {
+    title,
+    style: {
+      display: "flex",
+      alignItems: "center",
+      gap: "6px",
+      padding: "5px 10px",
+      cursor: "pointer",
+      userSelect: "none",
+      color: checked ? DEVTOOL_COLOR_TEXT_SECONDARY : DEVTOOL_COLOR_TEXT_MUTED,
+      fontSize: "10px",
+      fontFamily: SANS_FONT2
+    },
+    children: [
+      /* @__PURE__ */ jsx23("input", {
+        type: "checkbox",
+        checked,
+        onChange: (e) => onChange(e.target.checked),
+        style: { accentColor: DEVTOOL_COLOR_SEMANTIC_SYSTEM, cursor: "pointer", margin: 0 }
+      }),
+      children
+    ]
+  });
+}
 export {
   NiceActionDevtools,
   ActionDevtoolsCore

package/build/index.js

@@ -1803,20 +1803,24 @@ class ConnectionTransportManager {
   addTransport(transport) {
     this._transports.push(transport);
   }
+  getPreferredTransport() {
+    return this._transports[0];
+  }
   async getReadyTransport(routeActionParams) {
-    const initializingWaiters = [];
-    const unavailableTransports = [];
     const action = routeActionParams.action;
+    const candidates = [];
+    const unavailableTransports = [];
     for (const transport of this._transports) {
       const cacheKey = transport.getCacheKey(routeActionParams);
       if (cacheKey != null) {
         const cached = this._cache.get(cacheKey);
         if (cached != null) {
           if (cached instanceof Promise) {
-            initializingWaiters.push(cached);
+            candidates.push(cached);
             continue;
           }
-          return { ...cached, transport };
+          candidates.push(Promise.resolve({ ...cached, transport }));
+          break;
         }
       }
       const statusInfo = transport.getTransport(routeActionParams);
@@ -1826,7 +1830,8 @@ class ConnectionTransportManager {
           this._cache.set(cacheKey, { methods: readyData, transport });
           readyData.addOnDisconnectListener?.(() => this._cache.delete(cacheKey));
         }
-        return { methods: readyData, transport };
+        candidates.push(Promise.resolve({ methods: readyData, transport }));
+        break;
       }
       if (statusInfo.status === "unsupported" /* unsupported */) {
         unavailableTransports.push(transport);
@@ -1856,10 +1861,10 @@ class ConnectionTransportManager {
         if (cacheKey != null) {
           this._cache.set(cacheKey, promise);
         }
-        initializingWaiters.push(promise);
+        candidates.push(promise);
       }
     }
-    if (initializingWaiters.length === 0) {
+    if (candidates.length === 0) {
       if (unavailableTransports.length > 0) {
         throw err_nice_transport.fromId("unsupported" /* unsupported */, {
           transportTypes: unavailableTransports.map((t) => t.type)
@@ -1869,13 +1874,17 @@ class ConnectionTransportManager {
         actionId: action.id
       });
     }
-    try {
-      return await Promise.any(initializingWaiters).then();
-    } catch (e) {
-      throw err_nice_transport.fromId("initialization_failed" /* initialization_failed */, {
-        actionId: action.id
-      }).withOriginError(e);
+    let lastError;
+    for (const candidate of candidates) {
+      try {
+        return await candidate;
+      } catch (e) {
+        lastError = e;
+      }
     }
+    throw err_nice_transport.fromId("initialization_failed" /* initialization_failed */, {
+      actionId: action.id
+    }).withOriginError(lastError);
   }
 }
 
@@ -1935,20 +1944,19 @@ class ActionExternalClientHandler extends ActionHandler {
     const incomingTimeout = config?.timeout ?? this._defaultTimeout;
     const parentCuid = peekHandlerCuid();
     const callSite = action._callSite ?? new Error().stack;
-    const { methods, transport } = await this.transportManager.getReadyTransport({
+    const routeParams = {
       action,
       localClient,
       externalClient: this.externalClient
-    });
-    action.context.addRouteItem({
+    };
+    const preferredTransport = this.transportManager.getPreferredTransport();
+    const routeItem = preferredTransport != null ? {
       runtime: localClient,
-      handler: this.toHandlerRouteItem(transport, {
-        action,
-        localClient,
-        externalClient: this.externalClient
-      }),
+      handler: this.toHandlerRouteItem(preferredTransport, routeParams),
       time: Date.now()
-    });
+    } : undefined;
+    if (routeItem != null)
+      action.context.addRouteItem(routeItem);
     const runningAction = new RunningAction({
       context: action.context,
       request: action,
@@ -1956,23 +1964,37 @@ class ActionExternalClientHandler extends ActionHandler {
       callSite
     });
     localRuntime.registerRunningAction(runningAction);
-    const routeActionParams = {
-      action,
-      runningAction,
-      localClient,
-      externalClient: this.externalClient,
-      timeout: incomingTimeout
-    };
-    if (action.type === "request" /* request */ && methods.updateRunConfig != null) {
-      const runConfig = methods.updateRunConfig(routeActionParams);
-      routeActionParams.timeout = runConfig?.timeout ?? incomingTimeout;
-    }
+    this._dispatchWhenTransportReady(runningAction, routeParams, routeItem, incomingTimeout);
+    return runningAction;
+  }
+  async _dispatchWhenTransportReady(runningAction, routeParams, routeItem, incomingTimeout) {
+    const action = routeParams.action;
     try {
-      methods.sendActionData(routeActionParams);
+      const { methods, transport } = await this.transportManager.getReadyTransport(routeParams);
+      const handlerRouteItem = this.toHandlerRouteItem(transport, routeParams);
+      if (routeItem != null) {
+        routeItem.handler = handlerRouteItem;
+        routeItem.time = Date.now();
+      } else {
+        action.context.addRouteItem({
+          runtime: routeParams.localClient,
+          handler: handlerRouteItem,
+          time: Date.now()
+        });
+      }
+      const sendInput = {
+        ...routeParams,
+        runningAction,
+        timeout: incomingTimeout
+      };
+      if (action.type === "request" /* request */ && methods.updateRunConfig != null) {
+        const runConfig = methods.updateRunConfig(sendInput);
+        sendInput.timeout = runConfig?.timeout ?? incomingTimeout;
+      }
+      methods.sendActionData(sendInput);
     } catch (err3) {
       runningAction._abort(err3);
     }
-    return runningAction;
   }
   async sendReturnPayload(payload, config) {
     const localClient = config.targetLocalRuntime.coordinate;
@@ -2934,6 +2956,9 @@ function createBinaryWsSessionFactory(domains, options) {
     };
   };
 }
+// src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/secureWsChannel.ts
+import { ClientCryptoKeyLink } from "@nice-code/util";
+
 // src/utils/decodeActionFrame.ts
 function decodeActionFrame(frame, decoder) {
   const decoded = decoder?.incoming?.(frame) ?? (typeof frame === "string" ? parseJsonActionFrame(frame) : undefined);
@@ -3291,6 +3316,44 @@ class WebSocketTransport extends Transport {
     };
   }
 }
+
+// src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/secureWsChannel.ts
+function deriveDictionaryVersion(domains) {
+  const { intToRoute } = buildActionRouteDictionary(domains);
+  const signature = intToRoute.map((route) => `${route.domain}:${route.id}`).join(",");
+  let hash = 2166136261;
+  for (let i = 0;i < signature.length; i++) {
+    hash ^= signature.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `auto:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+function defineSecureWsChannel(options) {
+  return {
+    dictionaryVersion: options.dictionaryVersion ?? deriveDictionaryVersion(options.domains),
+    createCodec: createBinaryWsSessionFactory(options.domains, options.sessionOptions)
+  };
+}
+function createSecureWebSocketTransport(options) {
+  const link = new ClientCryptoKeyLink({ storageAdapter: options.storageAdapter });
+  return WebSocketTransport.create({
+    createWebSocket: options.createWebSocket ?? (() => {
+      const ws = new WebSocket(options.url);
+      ws.binaryType = "arraybuffer";
+      return ws;
+    }),
+    getTransportCacheKey: options.getTransportCacheKey ?? (() => [options.url]),
+    createFormatMessage: options.channel.createCodec,
+    updateRunConfig: options.updateRunConfig,
+    getRouteInfo: options.getRouteInfo,
+    security: {
+      securityLevel: options.securityLevel,
+      link,
+      localCoordinate: options.runtime.coordinate.toJsonObject(),
+      dictionaryVersion: options.channel.dictionaryVersion
+    }
+  });
+}
 // src/ActionRuntime/Handler/Server/ActionServerHandler.ts
 class ActionServerHandler extends ActionExternalClientHandler {
   _formatMessage;
@@ -3343,6 +3406,9 @@ class ActionServerHandler extends ActionExternalClientHandler {
   _setIncomingActionDataListener(listener) {
     this._incomingListeners.push(listener);
   }
+  setOnConnectionBound(onConnectionBound) {
+    this._onConnectionBound = onConnectionBound;
+  }
   receive(connection, frame) {
     if (this._security == null || !this._handshakeMode) {
       this._receivePlain(connection, frame);
@@ -3605,6 +3671,42 @@ class ActionServerHandler extends ActionExternalClientHandler {
 var createServerHandler = (options) => {
   return new ActionServerHandler(options);
 };
+// src/ActionRuntime/Handler/Server/createSecureActionServer.ts
+import { ClientCryptoKeyLink as ClientCryptoKeyLink2 } from "@nice-code/util";
+var DEFAULT_SERVER_SECURITY_LEVELS = [
+  "none" /* none */,
+  "authenticated" /* authenticated */,
+  "encrypted" /* encrypted */
+];
+function createSecureActionServerHandler(options) {
+  const link = new ClientCryptoKeyLink2({ storageAdapter: options.storageAdapter });
+  return new ActionServerHandler({
+    clientEnv: options.clientEnv,
+    createFormatMessage: options.channel.createCodec,
+    send: options.send,
+    defaultTimeout: options.defaultTimeout,
+    security: {
+      securityLevel: options.securityLevel ?? DEFAULT_SERVER_SECURITY_LEVELS,
+      link,
+      localCoordinate: options.runtime.coordinate.toJsonObject(),
+      dictionaryVersion: options.channel.dictionaryVersion,
+      verifyKeyResolver: options.verifyKeyResolver ?? createStorageTofuVerifyKeyResolver(options.storageAdapter)
+    }
+  });
+}
+function createHibernatableWsServerAdapter(options) {
+  const { handler, getWebSockets, getAttachment, setAttachment } = options;
+  handler.setOnConnectionBound(setAttachment);
+  for (const connection of getWebSockets()) {
+    const binding = getAttachment(connection);
+    if (binding != null)
+      handler.rehydrateConnection(connection, binding);
+  }
+  return {
+    receive: (connection, frame) => handler.receive(connection, frame),
+    drop: (connection) => handler.dropConnection(connection)
+  };
+}
 export {
   runtimeLinkId,
   isActionPayload_Result_JsonObject,
@@ -3615,13 +3717,17 @@ export {
   err_nice_external_client,
   err_nice_action,
   encodeHandshakeMessage,
+  defineSecureWsChannel,
   decodeHandshakeMessage,
   decodeActionFrame,
   createStorageTofuVerifyKeyResolver,
   createServerHandshake,
   createServerHandler,
+  createSecureWebSocketTransport,
+  createSecureActionServerHandler,
   createLocalHandler,
   createInMemoryTofuVerifyKeyResolver,
+  createHibernatableWsServerAdapter,
   createExternalClientHandler,
   createClientHandshake,
   createBinaryWsSessionFactory,

package/build/types/ActionRuntime/Handler/ExternalClient/ActionExternalClientHandler.d.ts

@@ -27,6 +27,7 @@ export declare class ActionExternalClientHandler extends ActionHandler<EActionHa
     forActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actionSchema"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS): this;
     _setIncomingActionDataListener(listener: (json: TActionPayload_Any_JsonObject<any, any>) => void): void;
     handleActionRequest<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions): Promise<RunningAction<DOM, ID>>;
+    private _dispatchWhenTransportReady;
     /**
      * Dispatch a result or progress payload directly back to the external client via the best
      * available bidirectional transport (WebSocket / Custom). Used for return-path routing when the

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/ConnectionTransportManager.d.ts

@@ -5,5 +5,12 @@ export declare class ConnectionTransportManager {
     private _transports;
     constructor(_cache: TTransportCache);
     addTransport(transport: TransportConnection): void;
+    /**
+     * The highest-priority transport (first declared). Used to label an action's route *before* the
+     * transport has finished connecting — so a still-connecting action shows its (expected) destination
+     * instead of an "unknown" hop. {@link getReadyTransport} still decides the real winner, and the
+     * caller corrects the hop if a lower-priority transport ends up serving the action.
+     */
+    getPreferredTransport(): TransportConnection | undefined;
     getReadyTransport(routeActionParams: ITransportRouteActionParams): Promise<IActionTransportReady>;
 }

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/secureWsChannel.d.ts

@@ -0,0 +1,63 @@
+import { type StorageAdapter } from "@nice-code/util";
+import type { ActionDomain } from "../../../../../ActionDefinition/Domain/ActionDomain";
+import type { ActionRuntime } from "../../../../ActionRuntime";
+import type { ITransportRouteActionParams, ITransportRouteInfo, TUpdateActionRunConfig } from "../Transport.types";
+import { ESecurityLevel } from "./actionWsHandshake";
+import { type IBinaryWsSessionOptions } from "./createBinaryWsSessionFactory";
+import type { IActionTransportReadyData_Ws } from "./TransportWebSocket.types";
+import { WebSocketTransport } from "./WebSocketTransport";
+/** The per-connection binary session codec — built once per socket from the channel's domains. */
+type TChannelCodec = NonNullable<IActionTransportReadyData_Ws["formatMessage"]>;
+/**
+ * The shared identity of a secure WebSocket channel: the wire dictionary version both ends check
+ * during the handshake, plus the per-connection codec factory both ends build from the *same* domain
+ * list. Define it once (typically in code shared by client and server) and hand it to
+ * {@link createSecureWebSocketTransport} on the client and `createSecureActionServerHandler` on the
+ * server, so the codec and version can never drift apart.
+ */
+export interface ISecureWsChannel {
+    /** Wire dictionary version — derived from the domains by default; the handshake rejects a mismatch. */
+    dictionaryVersion: string;
+    /** Per-connection session codec factory (call once per live connection). */
+    createCodec: () => TChannelCodec;
+}
+/**
+ * Bundle a secure channel's shared identity from its transported domains. Both ends MUST call this
+ * with the same domains in the same order (the binary wire dictionary is positional). The
+ * `dictionaryVersion` is derived from those domains unless you pin an explicit one.
+ */
+export declare function defineSecureWsChannel(options: {
+    /** Domains transported over this channel, in a stable order. Add new ones to the *end*. */
+    domains: ActionDomain<any>[];
+    /** Pin a human-readable version instead of the derived hash (must match on both ends). */
+    dictionaryVersion?: string;
+    /** Tuning for the per-connection binary session (e.g. correlation TTL). */
+    sessionOptions?: IBinaryWsSessionOptions;
+}): ISecureWsChannel;
+export interface ISecureWebSocketTransportOptions {
+    /** The shared channel identity (codec + dictionary version). */
+    channel: ISecureWsChannel;
+    /** This client's runtime — its coordinate is the authenticated identity sent in the handshake. */
+    runtime: ActionRuntime;
+    /** Backing store for this client's crypto identity (a stable verify key across reloads). */
+    storageAdapter: StorageAdapter;
+    /** The level this client requests; the server must allow it. */
+    securityLevel: ESecurityLevel;
+    /** Endpoint URL — drives both the socket and the per-endpoint cache key. */
+    url: string;
+    /** Override socket creation (defaults to a `new WebSocket(url)` with `binaryType = "arraybuffer"`). */
+    createWebSocket?: (input: ITransportRouteActionParams) => WebSocket;
+    /** Override the reuse key (defaults to `[url]`, so one socket is shared per endpoint). */
+    getTransportCacheKey?: (input: ITransportRouteActionParams) => string[];
+    updateRunConfig?: TUpdateActionRunConfig;
+    getRouteInfo?: (input: ITransportRouteActionParams) => ITransportRouteInfo;
+}
+/**
+ * Build a {@link WebSocketTransport} for the secure binary channel with the boilerplate folded in: it
+ * creates the {@link ClientCryptoKeyLink} from `storageAdapter`, opens an `arraybuffer` socket to
+ * `url`, caches it per endpoint, installs the channel's per-connection codec, and assembles the
+ * `security` block from the runtime coordinate + channel version. Pass `createWebSocket` /
+ * `getTransportCacheKey` to take over those bits when you need to.
+ */
+export declare function createSecureWebSocketTransport(options: ISecureWebSocketTransportOptions): WebSocketTransport;
+export {};

package/build/types/ActionRuntime/Handler/Server/ActionServerHandler.d.ts

@@ -117,7 +117,7 @@ export declare class ActionServerHandler<TConn = unknown> extends ActionExternal
     private readonly _createFormatMessage?;
     private readonly _send;
     private readonly _serverTimeout;
-    private readonly _onConnectionBound?;
+    private _onConnectionBound?;
     /** Incoming-data listeners installed by the runtime (`resolveIncomingActionPayload`). */
     private readonly _incomingListeners;
     private readonly _security?;
@@ -142,6 +142,12 @@ export declare class ActionServerHandler<TConn = unknown> extends ActionExternal
      */
     private _codecFor;
     _setIncomingActionDataListener(listener: (json: TActionPayload_Any_JsonObject<any>) => void): void;
+    /**
+     * Register (or replace) the connection-bound persistence callback after construction. Used by
+     * lifecycle helpers like {@link createHibernatableWsServerAdapter} so persistence and replay are
+     * owned by one place instead of being split across the constructor options.
+     */
+    setOnConnectionBound(onConnectionBound: (connection: TConn, binding: IActionServerConnectionBinding) => void): void;
     /**
      * Feed one inbound frame from a connection into the runtime. Decodes text or binary, binds the
      * connection to the requesting client's identity, then routes it (requests execute locally;

package/build/types/ActionRuntime/Handler/Server/createSecureActionServer.d.ts

@@ -0,0 +1,71 @@
+import { type StorageAdapter } from "@nice-code/util";
+import type { ActionRuntime } from "../../ActionRuntime";
+import type { RuntimeCoordinate } from "../../RuntimeCoordinate";
+import { ESecurityLevel, type IClientVerifyKeyResolver } from "../ExternalClient/Transport/WebSocket/actionWsHandshake";
+import type { ISecureWsChannel } from "../ExternalClient/Transport/WebSocket/secureWsChannel";
+import { ActionServerHandler, type IActionServerConnectionBinding } from "./ActionServerHandler";
+export interface ISecureActionServerHandlerOptions<TConn> {
+    /** The shared channel identity (codec + dictionary version) — same one the clients use. */
+    channel: ISecureWsChannel;
+    /**
+     * Coordinate of the *connecting clients* (typically env-only, e.g. `RuntimeCoordinate.env("web_app")`),
+     * used to route results/pushes back over this handler.
+     */
+    clientEnv: RuntimeCoordinate;
+    /** This server's runtime — its coordinate is the server identity presented in the handshake. */
+    runtime: ActionRuntime;
+    /**
+     * One backing store for the server's crypto identity *and* its trust-on-first-use verify-key pins.
+     * Their keys don't collide, so a single adapter is enough; back it with persistent storage (e.g. a
+     * Durable Object's storage) so identity and pins survive eviction.
+     */
+    storageAdapter: StorageAdapter;
+    /** Write an encoded frame to a specific live connection (e.g. `(ws, frame) => ws.send(frame)`). */
+    send: (connection: TConn, frame: string | Uint8Array | ArrayBuffer) => void;
+    /** Accepted level(s); defaults to negotiating any of none/authenticated/encrypted. */
+    securityLevel?: ESecurityLevel | readonly ESecurityLevel[];
+    /** Trust decision for a client's verify key; defaults to storage-backed TOFU over `storageAdapter`. */
+    verifyKeyResolver?: IClientVerifyKeyResolver;
+    /** Timeout (ms) applied to server-initiated actions awaiting a client response. */
+    defaultTimeout?: number;
+}
+/**
+ * Build an {@link ActionServerHandler} for the secure binary channel with the boilerplate folded in:
+ * it creates the {@link ClientCryptoKeyLink} and the storage-backed TOFU resolver from a single
+ * `storageAdapter`, installs the channel's per-connection codec, and assembles the `security` block
+ * from the runtime coordinate + channel version (accepting all three levels by default).
+ *
+ * For a hibernatable transport (e.g. a Durable Object), pair it with
+ * {@link createHibernatableWsServerAdapter} to wire persistence + replay.
+ */
+export declare function createSecureActionServerHandler<TConn = unknown>(options: ISecureActionServerHandlerOptions<TConn>): ActionServerHandler<TConn>;
+export interface IHibernatableWsServerAdapterOptions<TConn> {
+    /** The handler to drive (from {@link createSecureActionServerHandler} or `createServerHandler`). */
+    handler: ActionServerHandler<TConn>;
+    /** All currently-live connections — replayed on construction to rebuild bindings after a wake. */
+    getWebSockets: () => TConn[];
+    /** Read a connection's persisted binding (e.g. `(ws) => ws.deserializeAttachment()`). */
+    getAttachment: (connection: TConn) => IActionServerConnectionBinding | undefined;
+    /** Persist a connection's binding when it is bound (e.g. `(ws, b) => ws.serializeAttachment(b)`). */
+    setAttachment: (connection: TConn, binding: IActionServerConnectionBinding) => void;
+}
+export interface IHibernatableWsServerAdapter<TConn> {
+    /** Feed one inbound frame from a connection into the handler. */
+    receive: (connection: TConn, frame: string | ArrayBuffer | Uint8Array) => void;
+    /** Forget a connection (call on socket close/error). */
+    drop: (connection: TConn) => void;
+}
+/**
+ * Wire the hibernation lifecycle for a server handler on a transport whose sockets outlive process
+ * eviction (e.g. a Durable Object's hibernatable WebSockets). It owns persistence end to end:
+ * registers `setAttachment` as the handler's connection-bound callback and immediately replays every
+ * live connection's stored binding via `getAttachment`, so results/pushes still route after a wake.
+ *
+ * Construct it once when the handler is built, then forward socket events:
+ * ```ts
+ * const wsServer = createHibernatableWsServerAdapter({ handler, getWebSockets, getAttachment, setAttachment });
+ * // webSocketMessage(ws, msg) => wsServer.receive(ws, msg);
+ * // webSocketClose/Error(ws)  => wsServer.drop(ws);
+ * ```
+ */
+export declare function createHibernatableWsServerAdapter<TConn>(options: IHibernatableWsServerAdapterOptions<TConn>): IHibernatableWsServerAdapter<TConn>;

package/build/types/index.d.ts

@@ -26,10 +26,12 @@ export { createActionFrameCrypto, type IActionFrameCrypto, type IActionFrameCryp
 export { createClientHandshake, createInMemoryTofuVerifyKeyResolver, createServerHandshake, createStorageTofuVerifyKeyResolver, decodeHandshakeMessage, EHandshakeMessageType, ESecurityLevel, encodeHandshakeMessage, type IClientHandshakeConfig, type IClientVerifyKeyResolveInput, type IClientVerifyKeyResolver, type IHandshakeEncryptionKeyMaterial, type IHandshakeResult, type IServerHandshakeConfig, runtimeLinkId, type THandshakeMessage, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/actionWsHandshake";
 export { createBinaryWsAdapter } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/createBinaryWsAdapter";
 export { createBinaryWsSessionFactory, type IBinaryWsSessionOptions, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/createBinaryWsSessionFactory";
+export { createSecureWebSocketTransport, defineSecureWsChannel, type ISecureWebSocketTransportOptions, type ISecureWsChannel, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/secureWsChannel";
 export type { IActionTransportDef_Ws, IActionTransportInitialized_Ws, IActionTransportReadyData_Ws, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/TransportWebSocket.types";
 export { type IWebSocketTransportAdvancedOptions, type IWebSocketTransportSocketOptions, type TWebSocketTransportOptions, WebSocketTransport, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport";
 export { ActionLocalHandler, createLocalHandler, } from "./ActionRuntime/Handler/Local/ActionLocalHandler";
 export { ActionServerHandler, createServerHandler, type IActionServerConnectionBinding, type IActionServerHandlerOptions, type TActionChannelFormatMessage, type TActionConnectionEncoding, } from "./ActionRuntime/Handler/Server/ActionServerHandler";
+export { createHibernatableWsServerAdapter, createSecureActionServerHandler, type IHibernatableWsServerAdapter, type IHibernatableWsServerAdapterOptions, type ISecureActionServerHandlerOptions, } from "./ActionRuntime/Handler/Server/createSecureActionServer";
 export * from "./ActionRuntime/RuntimeCoordinate";
 export { EErrId_NiceAction, err_nice_action } from "./errors/err_nice_action";
 export { decodeActionFrame, type IActionFrameDecoder } from "./utils/decodeActionFrame";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/action",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -44,9 +44,9 @@
     "build-types": "tsc --project tsconfig.build.json"
   },
   "dependencies": {
-    "@nice-code/common-errors": "0.6.2",
-    "@nice-code/error": "0.6.2",
-    "@nice-code/util": "0.6.2",
+    "@nice-code/common-errors": "0.7.0",
+    "@nice-code/error": "0.7.0",
+    "@nice-code/util": "0.7.0",
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/react-virtual": "^3.13.26",
     "http-status-codes": "^2.3.0",