@fuzdev/fuz_app 0.24.0 → 0.26.0

package/dist/actions/action_codegen.d.ts

@@ -110,5 +110,30 @@ export declare const to_action_spec_output_identifier: (method: string) => strin
  */
 export declare const get_innermost_type: (schema: z.ZodType) => z.ZodType;
 export declare const get_innermost_type_name: (schema: z.ZodType) => string;
+/**
+ * Generates one method line of the typed `ActionsApi` interface for a single
+ * spec. Encapsulates the input/options/return-type signature shape so the
+ * surface evolves in one place when fields like `signal` or `transport_name`
+ * are added to per-call options.
+ *
+ * Async methods (request_response, async local_call) get an optional second
+ * `options?: RpcClientCallOptions` arg (`{signal?, transport_name?}`). Sync
+ * local_call methods omit the options arg — `signal` can't cooperatively
+ * interrupt a synchronous handler and there's no transport to select.
+ *
+ * Consumers must import `ActionInputs`, `ActionOutputs`, `Result`,
+ * `JsonrpcErrorObject`, and (for async) `RpcClientCallOptions` into the
+ * generated module — the helper only emits the type references.
+ *
+ * @param spec - the action spec to emit
+ * @param options.sync_returns_value - when true (default), sync local_call
+ *   methods return the output value directly; when false they're wrapped in
+ *   `Result<{value, error}>` like async methods. Set to `false` if your
+ *   ActionsApi treats every method uniformly.
+ * @returns one line like `foo: (input: ActionInputs['foo'], options?: RpcClientCallOptions) => Promise<Result<...>>;`
+ */
+export declare const generate_actions_api_method_signature: (spec: ActionSpecUnion, options?: {
+    sync_returns_value?: boolean;
+}) => string;
 export {};
 //# sourceMappingURL=action_codegen.d.ts.map

package/dist/actions/action_codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,eAAe,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAOxE;;GAEG;AACH,UAAU,UAAU;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa;;IACzB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAa;IAE1D;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAOrD;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAgCtD;;;OAGG;IACH,KAAK,IAAI,MAAM;IAIf;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;IAIxB;;OAEG;IACH,KAAK,IAAI,IAAI;CAqDb;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,KAC9B,KAAK,CAAC,gBAAgB,CA4DxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,OAAO,gBAAgB,EACvB,SAAS,aAAa,EACtB,aAAa,MAAM,KACjB,MAkBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,EAChC,SAAS,aAAa,EACtB,UAAU;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAC,KACpC,MA4BF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,aAAa,MAAM,KAAG,MACU,CAAC;AAG/D,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,MAAiC,CAAC;AAC7F,eAAO,MAAM,+BAA+B,GAAI,QAAQ,MAAM,KAAG,MACpB,CAAC;AAC9C,eAAO,MAAM,gCAAgC,GAAI,QAAQ,MAAM,KAAG,MACpB,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,CAAC,CAAC,OAwBxD,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,MAI3D,CAAC"}
+{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,eAAe,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAOxE;;GAEG;AACH,UAAU,UAAU;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa;;IACzB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAa;IAE1D;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAOrD;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAgCtD;;;OAGG;IACH,KAAK,IAAI,MAAM;IAIf;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;IAIxB;;OAEG;IACH,KAAK,IAAI,IAAI;CAqDb;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,KAC9B,KAAK,CAAC,gBAAgB,CA4DxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,OAAO,gBAAgB,EACvB,SAAS,aAAa,EACtB,aAAa,MAAM,KACjB,MAkBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,EAChC,SAAS,aAAa,EACtB,UAAU;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAC,KACpC,MA4BF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,aAAa,MAAM,KAAG,MACU,CAAC;AAG/D,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,MAAiC,CAAC;AAC7F,eAAO,MAAM,+BAA+B,GAAI,QAAQ,MAAM,KAAG,MACpB,CAAC;AAC9C,eAAO,MAAM,gCAAgC,GAAI,QAAQ,MAAM,KAAG,MACpB,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,CAAC,CAAC,OAwBxD,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,MAI3D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,eAAe,EACrB,UAAU;IAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAC,KACtC,MAmBF,CAAC"}

package/dist/actions/action_codegen.js

@@ -316,3 +316,42 @@ export const get_innermost_type_name = (schema) => {
     const def = innermost.def;
     return def.type;
 };
+/**
+ * Generates one method line of the typed `ActionsApi` interface for a single
+ * spec. Encapsulates the input/options/return-type signature shape so the
+ * surface evolves in one place when fields like `signal` or `transport_name`
+ * are added to per-call options.
+ *
+ * Async methods (request_response, async local_call) get an optional second
+ * `options?: RpcClientCallOptions` arg (`{signal?, transport_name?}`). Sync
+ * local_call methods omit the options arg — `signal` can't cooperatively
+ * interrupt a synchronous handler and there's no transport to select.
+ *
+ * Consumers must import `ActionInputs`, `ActionOutputs`, `Result`,
+ * `JsonrpcErrorObject`, and (for async) `RpcClientCallOptions` into the
+ * generated module — the helper only emits the type references.
+ *
+ * @param spec - the action spec to emit
+ * @param options.sync_returns_value - when true (default), sync local_call
+ *   methods return the output value directly; when false they're wrapped in
+ *   `Result<{value, error}>` like async methods. Set to `false` if your
+ *   ActionsApi treats every method uniformly.
+ * @returns one line like `foo: (input: ActionInputs['foo'], options?: RpcClientCallOptions) => Promise<Result<...>>;`
+ */
+export const generate_actions_api_method_signature = (spec, options) => {
+    const sync_returns_value = options?.sync_returns_value ?? true;
+    const innermost_type_name = get_innermost_type_name(spec.input);
+    const has_input = innermost_type_name !== 'null' && innermost_type_name !== 'void';
+    const input_param = has_input
+        ? `input${spec.input.safeParse(undefined).success ? '?' : ''}: ActionInputs['${spec.method}']`
+        : 'input?: void';
+    const is_async = spec.kind === 'request_response' || (spec.kind === 'local_call' && spec.async);
+    const options_param = is_async ? ', options?: RpcClientCallOptions' : '';
+    const result_return = `Result<{value: ActionOutputs['${spec.method}']}, {error: JsonrpcErrorObject}>`;
+    const return_type = is_async
+        ? `Promise<${result_return}>`
+        : sync_returns_value
+            ? `ActionOutputs['${spec.method}']`
+            : result_return;
+    return `${spec.method}: (${input_param}${options_param}) => ${return_type};`;
+};

package/dist/actions/action_peer.d.ts

@@ -11,6 +11,13 @@ import { Transports, type TransportName } from './transports.js';
 import type { ActionEventEnvironment } from './action_event_types.js';
 export interface ActionPeerSendOptions {
     transport_name?: TransportName;
+    /**
+     * Per-call `AbortSignal`. Forwarded into the chosen transport's `send`,
+     * which bottoms out at `FrontendWebsocketClient.request({signal})` for WS
+     * (sends the shared `cancel` notification on abort) and at
+     * `fetch({signal})` for HTTP. Backend transport ignores it.
+     */
+    signal?: AbortSignal;
 }
 export interface ActionPeerOptions {
     environment: ActionEventEnvironment;

package/dist/actions/action_peer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action_peer.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_peer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEN,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,EAAC,UAAU,EAAE,KAAK,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,MAAM,WAAW,qBAAqB;IACrC,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,sBAAsB,CAAC;IAGpC,UAAU,CAAC,EAAE,UAAU,CAAC;IAGxB,oBAAoB,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACtD;AAED,qBAAa,UAAU;;IACtB,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAMhC,oBAAoB,EAAE,qBAAqB,CAAC;gBAEhC,OAAO,EAAE,iBAAiB;IAOhC,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA2CjC,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC;CAyIjF"}
+{"version":3,"file":"action_peer.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_peer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEN,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,EAAC,UAAU,EAAE,KAAK,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,MAAM,WAAW,qBAAqB;IACrC,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,sBAAsB,CAAC;IAGpC,UAAU,CAAC,EAAE,UAAU,CAAC;IAGxB,oBAAoB,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACtD;AAED,qBAAa,UAAU;;IACtB,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAMhC,oBAAoB,EAAE,qBAAqB,CAAC;gBAEhC,OAAO,EAAE,iBAAiB;IAOhC,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA2CjC,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC;CAyIjF"}

package/dist/actions/action_peer.js

@@ -33,7 +33,7 @@ export class ActionPeer {
             }
             const message_type = is_jsonrpc_request(message) ? 'request' : 'notification';
             this.environment.log?.debug(`[peer] send ${message_type}:`, message.method, `via ${transport.transport_name}`);
-            const result = await transport.send(message);
+            const result = await transport.send(message, { signal: options?.signal });
             if (result && 'error' in result) {
                 this.environment.log?.error(`[peer] send ${message_type} failed:`, message.method, result.error.message);
             }

package/dist/actions/action_types.d.ts

@@ -9,6 +9,7 @@
  * @module
  */
 import type { JsonrpcRequestId } from '../http/jsonrpc.js';
+import type { Uuid } from '../uuid.js';
 import type { ActionSpecUnion } from './action_spec.js';
 /**
  * Minimum per-request context every server-side WS handler receives.
@@ -20,13 +21,27 @@ import type { ActionSpecUnion } from './action_spec.js';
 export interface BaseHandlerContext {
     /** JSON-RPC envelope request id — echoed back on the response. */
     request_id: JsonrpcRequestId;
+    /**
+     * Stable per-socket connection id assigned by
+     * `BackendWebsocketTransport.add_connection` — same reference across every
+     * message on this socket, also passed to `on_socket_open` /
+     * `on_socket_close`. Consumers key per-connection domain state on this
+     * directly instead of trying to derive it from signals (which are
+     * per-message composites of `AbortSignal.any([socket, request])`).
+     */
+    connection_id: Uuid;
     /**
      * Send a request-scoped JSON-RPC notification to the originating socket.
      * Not a broadcast — the message only reaches the client whose request
      * triggered this handler.
      */
     notify: (method: string, params: unknown) => void;
-    /** Fires on socket close; streaming handlers poll for early termination. */
+    /**
+     * Fires on socket close OR on a client-initiated `cancel` notification
+     * matching this request's id. Streaming handlers poll for early
+     * termination; per-message composite (`AbortSignal.any([socket, request])`)
+     * — not stable across messages.
+     */
     signal: AbortSignal;
 }
 /**

package/dist/actions/action_types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action_types.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;;;OAIG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,4EAA4E;IAC5E,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,kBAAkB,GAAG,kBAAkB,IAAI,CACnF,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,IAAI,KACL,OAAO,CAAC;AAEb;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM,CAAC,IAAI,SAAS,kBAAkB,GAAG,kBAAkB;IAC3E,IAAI,EAAE,eAAe,CAAC;IACtB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC;CAChC"}
+{"version":3,"file":"action_types.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,YAAY,CAAC;AACrC,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;;;;;;OAOG;IACH,aAAa,EAAE,IAAI,CAAC;IACpB;;;;OAIG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD;;;;;OAKG;IACH,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,kBAAkB,GAAG,kBAAkB,IAAI,CACnF,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,IAAI,KACL,OAAO,CAAC;AAEb;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM,CAAC,IAAI,SAAS,kBAAkB,GAAG,kBAAkB;IAC3E,IAAI,EAAE,eAAe,CAAC;IACtB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC;CAChC"}

package/dist/actions/cancel.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared cancel action — the second composable fuz_app primitive, validating
+ * the spec+handler tuple pattern on a notification-kind action.
+ *
+ * Semantics: the client sends `{jsonrpc, method: 'cancel', params:
+ * {request_id}}` to abort an in-flight request on the same socket.
+ * {@link register_action_ws} intercepts this notification and aborts the
+ * matching pending request's `ctx.signal`. Unknown ids are no-ops by design —
+ * races between response arrival and cancel delivery are safe without extra
+ * coordination.
+ *
+ * The handler field is an empty stub: cancel semantics are dispatcher-owned
+ * (the dispatcher has the `{request_id → AbortController}` map, not the
+ * handler). The handler exists for symmetry with other composable primitives
+ * like {@link heartbeat_action}; the dispatcher never calls it. Consumers
+ * spread {@link cancel_action} into their server's `actions` array so
+ * `spec_by_method` knows about it (enabling input validation on incoming
+ * cancels) and so `create_rpc_client` codegen produces `app.api.cancel()`
+ * when desired — though `FrontendWebsocketClient.request({signal})` sends
+ * the cancel on abort without needing the typed API.
+ *
+ * Wire format is snake_case `cancel` with `{request_id}`, not MCP's
+ * `$/cancelRequest` with `{requestId}` — fuz_app's WS transport isn't MCP,
+ * and adopting MCP's convention would leak protocol-specific framing into
+ * the base transport. When MCP elicitation (Phase 5) lands, a translation
+ * layer at the MCP adapter is the right seam.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import type { Action } from './action_types.js';
+/** Method name on the wire — shared across every fuz_app consumer. */
+export declare const CANCEL_METHOD = "cancel";
+/**
+ * Params for a {@link CANCEL_METHOD} notification. `request_id` is the id of
+ * the pending request to abort. Must match the id of a request sent on the
+ * same socket; cancels from other sockets (or for unknown ids) are ignored.
+ */
+export declare const CancelNotificationParams: z.ZodObject<{
+    request_id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+}, z.core.$strict>;
+export type CancelNotificationParams = z.infer<typeof CancelNotificationParams>;
+/**
+ * `ActionSpec` for the shared cancel. `auth: null` matches every other
+ * remote-notification spec — upgrade-time auth has already admitted the
+ * socket, so per-action auth on a fire-and-forget notification is moot. The
+ * per-connection `{request_id → AbortController}` map enforces socket-scoped
+ * ownership naturally: a different socket's cancel for the same id misses
+ * in its own map.
+ */
+export declare const cancel_action_spec: {
+    method: string;
+    initiator: "both" | "frontend" | "backend";
+    input: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    description: string;
+    kind: "remote_notification";
+    auth: null;
+    side_effects: true;
+    output: z.ZodVoid;
+    async: true;
+    streams?: string | undefined;
+};
+/**
+ * Placeholder handler — cancel semantics are owned by {@link register_action_ws},
+ * not invoked per-handler. Exported for symmetry with the {@link Action}
+ * tuple shape; the dispatcher short-circuits cancel notifications before any
+ * handler lookup happens.
+ */
+export declare const cancel_handler: () => void;
+/**
+ * Composable tuple — spread into the server's `actions` array so the
+ * dispatcher registers the spec for input validation and so `create_rpc_client`
+ * codegen sees the method. The client doesn't need to call it directly;
+ * `FrontendWebsocketClient.request({signal})` sends the cancel notification
+ * automatically when the signal fires.
+ */
+export declare const cancel_action: Action;
+//# sourceMappingURL=cancel.d.ts.map

package/dist/actions/cancel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/cancel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAItB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;kBAEnC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;CAW7B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAAU,CAAC;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,MAG3B,CAAC"}

package/dist/actions/cancel.js

@@ -0,0 +1,79 @@
+/**
+ * Shared cancel action — the second composable fuz_app primitive, validating
+ * the spec+handler tuple pattern on a notification-kind action.
+ *
+ * Semantics: the client sends `{jsonrpc, method: 'cancel', params:
+ * {request_id}}` to abort an in-flight request on the same socket.
+ * {@link register_action_ws} intercepts this notification and aborts the
+ * matching pending request's `ctx.signal`. Unknown ids are no-ops by design —
+ * races between response arrival and cancel delivery are safe without extra
+ * coordination.
+ *
+ * The handler field is an empty stub: cancel semantics are dispatcher-owned
+ * (the dispatcher has the `{request_id → AbortController}` map, not the
+ * handler). The handler exists for symmetry with other composable primitives
+ * like {@link heartbeat_action}; the dispatcher never calls it. Consumers
+ * spread {@link cancel_action} into their server's `actions` array so
+ * `spec_by_method` knows about it (enabling input validation on incoming
+ * cancels) and so `create_rpc_client` codegen produces `app.api.cancel()`
+ * when desired — though `FrontendWebsocketClient.request({signal})` sends
+ * the cancel on abort without needing the typed API.
+ *
+ * Wire format is snake_case `cancel` with `{request_id}`, not MCP's
+ * `$/cancelRequest` with `{requestId}` — fuz_app's WS transport isn't MCP,
+ * and adopting MCP's convention would leak protocol-specific framing into
+ * the base transport. When MCP elicitation (Phase 5) lands, a translation
+ * layer at the MCP adapter is the right seam.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { JsonrpcRequestId } from '../http/jsonrpc.js';
+import { RemoteNotificationActionSpec } from './action_spec.js';
+/** Method name on the wire — shared across every fuz_app consumer. */
+export const CANCEL_METHOD = 'cancel';
+/**
+ * Params for a {@link CANCEL_METHOD} notification. `request_id` is the id of
+ * the pending request to abort. Must match the id of a request sent on the
+ * same socket; cancels from other sockets (or for unknown ids) are ignored.
+ */
+export const CancelNotificationParams = z.strictObject({
+    request_id: JsonrpcRequestId,
+});
+/**
+ * `ActionSpec` for the shared cancel. `auth: null` matches every other
+ * remote-notification spec — upgrade-time auth has already admitted the
+ * socket, so per-action auth on a fire-and-forget notification is moot. The
+ * per-connection `{request_id → AbortController}` map enforces socket-scoped
+ * ownership naturally: a different socket's cancel for the same id misses
+ * in its own map.
+ */
+export const cancel_action_spec = RemoteNotificationActionSpec.parse({
+    method: CANCEL_METHOD,
+    kind: 'remote_notification',
+    initiator: 'frontend',
+    auth: null,
+    side_effects: true,
+    input: CancelNotificationParams,
+    output: z.void(),
+    async: true,
+    description: 'Client-initiated cancellation of an in-flight request by id. Dispatcher-handled: aborts the ctx.signal of the matching pending request on the same socket. Unknown or completed ids no-op.',
+});
+/**
+ * Placeholder handler — cancel semantics are owned by {@link register_action_ws},
+ * not invoked per-handler. Exported for symmetry with the {@link Action}
+ * tuple shape; the dispatcher short-circuits cancel notifications before any
+ * handler lookup happens.
+ */
+export const cancel_handler = () => { }; // eslint-disable-line @typescript-eslint/no-empty-function
+/**
+ * Composable tuple — spread into the server's `actions` array so the
+ * dispatcher registers the spec for input validation and so `create_rpc_client`
+ * codegen sees the method. The client doesn't need to call it directly;
+ * `FrontendWebsocketClient.request({signal})` sends the cancel notification
+ * automatically when the signal fires.
+ */
+export const cancel_action = {
+    spec: cancel_action_spec,
+    handler: cancel_handler,
+};

package/dist/actions/register_action_ws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAgB1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,YAAY,CAAC;AAErC,OAAO,EAAC,KAAK,MAAM,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAE7F,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAE9F,YAAY,EAAC,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAC,CAAC;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,qFAAqF;IACrF,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,wFAAwF;IACxF,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,EAAE,EAAE,SAAS,CAAC;IACd,2CAA2C;IAC3C,aAAa,EAAE,IAAI,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,kBAAkB;IACvE,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;;OAMG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC;;;;;OAKG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,SAAS,kBAAkB,EACjE,SAAS,uBAAuB,CAAC,IAAI,CAAC,KACpC,sBA0UF,CAAC"}
+{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAgB1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,YAAY,CAAC;AAErC,OAAO,EAAC,KAAK,MAAM,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAG7F,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAE9F,YAAY,EAAC,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAC,CAAC;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,qFAAqF;IACrF,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,wFAAwF;IACxF,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,EAAE,EAAE,SAAS,CAAC;IACd,2CAA2C;IAC3C,aAAa,EAAE,IAAI,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,kBAAkB;IACvE,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;;OAMG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC;;;;;OAKG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,SAAS,kBAAkB,EACjE,SAAS,uBAAuB,CAAC,IAAI,CAAC,KACpC,sBA8WF,CAAC"}

package/dist/actions/register_action_ws.js

@@ -28,10 +28,11 @@ import { get_request_context, has_role } from '../auth/request_context.js';
 import { hash_session_token } from '../auth/session_queries.js';
 import { ROLE_KEEPER } from '../auth/role_schema.js';
 import { JSONRPC_VERSION } from '../http/jsonrpc.js';
-import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
+import { jsonrpc_error_messages, ThrownJsonrpcError } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, create_jsonrpc_error_response_from_thrown, create_jsonrpc_notification, to_jsonrpc_message_id, to_jsonrpc_params, is_jsonrpc_request, } from '../http/jsonrpc_helpers.js';
 import { CREDENTIAL_TYPE_KEY, AUTH_API_TOKEN_ID_KEY } from '../hono_context.js';
 import {} from './action_types.js';
+import { CANCEL_METHOD, CancelNotificationParams } from './cancel.js';
 import { WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT } from './transports.js';
 import { BackendWebsocketTransport } from './transports_ws_backend.js';
 /** Default inactivity window before the server closes a silent socket. */
@@ -88,12 +89,19 @@ export const register_action_ws = (options) => {
         // `close_sockets_for_token` to tear down just this socket on
         // `token_revoke` without affecting the account's other sockets.
         const api_token_id = c.get(AUTH_API_TOKEN_ID_KEY);
-        // Per-socket abort controller — fires on socket close, threaded into
-        // every in-flight handler's ctx.signal on this connection. A
-        // dedicated per-request controller linked to this is future work;
-        // a single socket-scoped signal is sufficient today since cancel
-        // granularity tracks connection lifetime, not individual requests.
+        // Per-socket abort controller — fires on socket close, chained into
+        // every in-flight handler's per-request controller via
+        // `AbortSignal.any`. Keeping both signals lets the client
+        // cancel-one-request-by-id (via the `cancel` notification) without
+        // tearing down the whole socket.
         const socket_abort_controller = new AbortController();
+        // Per-request controllers keyed by JSON-RPC request id — lets an
+        // incoming `cancel` notification abort just the matching handler.
+        // Populated on request dispatch, cleared in the handler's `finally`
+        // so a late-arriving cancel for a completed id (or a reused id)
+        // can't null-abort a freshly-arrived request. Idempotent: cancel
+        // for unknown ids no-ops.
+        const pending_controllers = new Map();
         // Identity is assembled at upgrade time so `on_socket_close` can
         // still read it after the audit guard tears the transport record
         // down; `BackendWebsocketTransport.#revoke_connection` clears the
@@ -126,10 +134,10 @@ export const register_action_ws = (options) => {
             }
         };
         return {
-            onOpen: async (event, ws) => {
+            onOpen: async (_event, ws) => {
                 const connection_id = transport.add_connection(ws, token_hash, account_id, api_token_id);
                 captured_connection_id = connection_id;
-                log.debug('ws opened', connection_id, event);
+                log.debug('ws opened', connection_id);
                 if (heartbeat_enabled) {
                     last_receive_time = Date.now();
                     heartbeat_timer = setInterval(() => {
@@ -185,9 +193,26 @@ export const register_action_ws = (options) => {
                     ws.send(JSON.stringify(create_jsonrpc_error_response(null, jsonrpc_error_messages.invalid_request('batch JSON-RPC requests are not supported on WebSocket'))));
                     return;
                 }
-                // Only handle requests (method + id). Notifications (no id) are silenced per JSON-RPC spec.
+                // Notifications (method + no id) — `cancel` is intercepted
+                // for request-scoped cancellation; other notifications are
+                // silenced per JSON-RPC spec (consumer notification handlers
+                // are not a feature yet).
                 if (!is_jsonrpc_request(json)) {
                     if (typeof json === 'object' && json !== null && 'method' in json && !('id' in json)) {
+                        if (json.method === CANCEL_METHOD) {
+                            const parsed = CancelNotificationParams.safeParse(json.params);
+                            if (!parsed.success) {
+                                log.debug('cancel: invalid params, ignoring', parsed.error.issues);
+                                return;
+                            }
+                            const controller = pending_controllers.get(parsed.data.request_id);
+                            if (controller) {
+                                controller.abort();
+                            }
+                            else {
+                                log.debug('cancel: no pending request for id', parsed.data.request_id);
+                            }
+                        }
                         return;
                     }
                     ws.send(JSON.stringify(create_jsonrpc_error_response(to_jsonrpc_message_id(json), jsonrpc_error_messages.invalid_request())));
@@ -233,22 +258,27 @@ export const register_action_ws = (options) => {
                     await wait(artificial_delay);
                 }
                 // Socket-scoped notification — routes to originator only, not
-                // broadcast. Future work: other audiences — account-scoped,
+                // broadcast. Same helper used in `on_socket_open` so both
+                // paths share one code path for send-and-log-on-failure.
+                // Future work: other audiences — account-scoped,
                 // ACL-filtered, broadcast — likely via a transport-level
                 // policy hook.
-                const notify = (notify_method, notify_params) => {
-                    try {
-                        const notification = create_jsonrpc_notification(notify_method, to_jsonrpc_params(notify_params));
-                        ws.send(JSON.stringify(notification));
-                    }
-                    catch (error) {
-                        log.error('notify send failed:', notify_method, error);
-                    }
-                };
+                const notify = notify_socket(ws);
+                // Per-request controller — fires on explicit `cancel` or on
+                // socket close (via the socket_abort_controller chain below).
+                // Registered before dispatch so a cancel arriving mid-handler
+                // finds it; cleared in `finally` so late cancels for a
+                // completed id (or a future request that reuses the id) can't
+                // null-abort the wrong handler.
+                const request_controller = new AbortController();
+                pending_controllers.set(id, request_controller);
                 const base = {
                     request_id: id,
+                    // Populated in `onOpen` before any message can dispatch —
+                    // non-null assertion is safe.
+                    connection_id: captured_connection_id,
                     notify,
-                    signal: socket_abort_controller.signal,
+                    signal: AbortSignal.any([socket_abort_controller.signal, request_controller.signal]),
                 };
                 const ctx = extend_context(base, c);
                 try {
@@ -264,9 +294,19 @@ export const register_action_ws = (options) => {
                     ws.send(JSON.stringify({ jsonrpc: JSONRPC_VERSION, id, result: output }));
                 }
                 catch (error) {
-                    log.error('handler error:', method, error);
+                    if (error instanceof ThrownJsonrpcError) {
+                        // Expected handler outcome (conflict, not_found, invalid_params, ...).
+                        // Log at debug without the stack — the throw site is part of protocol, not a bug.
+                        log.debug('handler error:', method, `${error.code} ${error.message}`);
+                    }
+                    else {
+                        log.error('handler error:', method, error);
+                    }
                     ws.send(JSON.stringify(create_jsonrpc_error_response_from_thrown(id, error)));
                 }
+                finally {
+                    pending_controllers.delete(id);
+                }
             },
             onClose: async (event, ws) => {
                 stop_heartbeat_timer();
@@ -284,7 +324,7 @@ export const register_action_ws = (options) => {
                     }
                 }
                 transport.remove_connection(ws);
-                log.debug('ws closed', event);
+                log.debug('ws closed', captured_connection_id, { code: event.code, reason: event.reason });
             },
         };
     }));

package/dist/actions/rpc_client.d.ts

@@ -57,4 +57,14 @@ export interface CreateRpcClientOptions {
  * @returns a Proxy that responds to any method name found in the environment's specs
  */
 export declare const create_rpc_client: (options: CreateRpcClientOptions) => Record<string, (...args: Array<any>) => any>;
+/**
+ * Per-call options accepted by every typed Proxy method. `signal` lets the
+ * caller cancel an in-flight request (sends the shared `cancel` notification
+ * on the WS path, aborts `fetch` on HTTP). `transport_name` overrides the
+ * per-method `transport_for_method` selector for this call.
+ */
+export interface RpcClientCallOptions {
+    signal?: AbortSignal;
+    transport_name?: TransportName;
+}
 //# sourceMappingURL=rpc_client.d.ts.map

package/dist/actions/rpc_client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;AAM/E,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,CAAC,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,oBAAoB,CAAA;KAAC,KAC5E;QACA,sBAAsB,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;KAC5C,GACD,SAAS,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,sBAAsB,KAC7B,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAgB7C,CAAC"}
+{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAGnD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;AAM/E,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,CAAC,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,oBAAoB,CAAA;KAAC,KAC5E;QACA,sBAAsB,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;KAC5C,GACD,SAAS,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,sBAAsB,KAC7B,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAgB7C,CAAC;AA2DF;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B"}

package/dist/actions/rpc_client.js

@@ -11,6 +11,7 @@
  */
 import { create_action_event } from './action_event.js';
 import { is_send_request, is_notification_send, extract_action_result, } from './action_event_helpers.js';
+import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 /**
  * Creates a Proxy-based API from action specs.
  *
@@ -78,9 +79,19 @@ const create_sync_local_call_method = (environment, spec, actions) => {
 /**
  * Creates an asynchronous local call method.
  * Returns Result for type-safe error handling.
+ *
+ * Local calls don't traverse a transport, so `transport_name` is ignored and
+ * `signal` can only short-circuit before the synchronous handler runs (no
+ * cooperative interrupt mid-handler).
  */
 const create_async_local_call_method = (environment, spec, actions) => {
-    return async (input) => {
+    return async (input, options) => {
+        if (options?.signal?.aborted) {
+            return {
+                ok: false,
+                error: jsonrpc_error_messages.internal_error(`${spec.method} aborted before execution`),
+            };
+        }
         const event = create_action_event(environment, spec, input);
         const action = actions?.add_from_json({
             method: spec.method,
@@ -95,7 +106,7 @@ const create_async_local_call_method = (environment, spec, actions) => {
  * Creates a request/response method that communicates over the network.
  */
 const create_request_response_method = (peer, environment, spec, actions, transport_for_method) => {
-    return async (input) => {
+    return async (input, options) => {
         const event = create_action_event(environment, spec, input);
         const action = actions?.add_from_json({
             method: spec.method,
@@ -113,8 +124,10 @@ const create_request_response_method = (peer, environment, spec, actions, transp
         if (event.data.step !== 'handled') {
             return extract_action_result(event);
         }
-        const transport_name = transport_for_method?.(spec.method);
-        const response = await peer.send(event.data.request, transport_name ? { transport_name } : undefined);
+        const response = await peer.send(event.data.request, {
+            transport_name: options?.transport_name ?? transport_for_method?.(spec.method),
+            signal: options?.signal,
+        });
         event.transition('receive_response');
         // TODO @api shouldn't this happen in the peer like the other method calls?
         event.set_response(response);
@@ -128,7 +141,7 @@ const create_request_response_method = (peer, environment, spec, actions, transp
  * Returns Result<{value: void}> for consistency.
  */
 const create_remote_notification_method = (peer, environment, spec, actions, transport_for_method) => {
-    return async (input) => {
+    return async (input, options) => {
         const event = create_action_event(environment, spec, input);
         const action = actions?.add_from_json({
             method: spec.method,
@@ -139,8 +152,10 @@ const create_remote_notification_method = (peer, environment, spec, actions, tra
         if (!is_notification_send(event.data))
             throw Error(); // TODO @many maybe make this an assertion helper?
         if (event.data.step === 'handled') {
-            const transport_name = transport_for_method?.(spec.method);
-            const send_result = await peer.send(event.data.notification, transport_name ? { transport_name } : undefined);
+            const send_result = await peer.send(event.data.notification, {
+                transport_name: options?.transport_name ?? transport_for_method?.(spec.method),
+                signal: options?.signal,
+            });
             // Check if notification failed to send
             if (send_result !== null) {
                 environment.log?.error('notification send failed:', send_result.error);