RPC agent stub visualization

total 352
drwxrwxr-x  10 jm jm   4096 Feb 22 20:36 .
drwxr-xr-x   3 jm jm     60 Feb 23 22:25 ..
drwxrwxr-x   2 jm jm   4096 Jan  1 00:31 .changeset
drwxrwxr-x   7 jm jm   4096 Feb 22 20:36 .git
drwxrwxr-x   3 jm jm   4096 Nov 25 07:32 .github
-rw-rw-r--   1 jm jm     73 Sep 23 18:58 .gitignore
-rw-rw-r--   1 jm jm   3607 Feb 22 20:36 CHANGELOG.md
-rw-rw-r--   1 jm jm   1073 Sep 23 18:58 LICENSE.txt
-rw-rw-r--   1 jm jm  40445 Feb 22 20:36 README.md
-rw-rw-r--   1 jm jm    739 Nov 25 07:32 SECURITY.md
drwxrwxr-x   2 jm jm   4096 Feb 22 20:36 __tests__
drwxrwxr-x   2 jm jm   4096 Nov 25 07:32 dist
drwxrwxr-x   4 jm jm   4096 Nov 25 07:37 examples
drwxrwxr-x 255 jm jm  12288 Nov 25 07:32 node_modules
-rw-rw-r--   1 jm jm 215699 Feb 22 20:36 package-lock.json
-rw-rw-r--   1 jm jm   1529 Feb 22 20:36 package.json
-rw-rw-r--   1 jm jm  18437 Feb 22 20:36 protocol.md
drwxrwxr-x   2 jm jm   4096 Feb 22 20:36 src
-rw-rw-r--   1 jm jm    340 Sep 23 18:58 tsconfig.json
-rw-rw-r--   1 jm jm    793 Jan  1 00:34 tsup.config.ts
-rw-rw-r--   1 jm jm   3560 Feb 22 20:36 vitest.config.ts
-rw-rw-r--   1 jm jm    322 Sep 23 18:58 vitest.shims.d.ts

All 2 tools executed successfully.

Keep using the batch tool for optimal performance in your next response!

<path>/nvme/code/capnweb/README.md</path>
<type>file</type>
<content>1: # Cap'n Web: A JavaScript-native RPC system
2: 
3: Cap'n Web is a spiritual sibling to [Cap'n Proto](https://capnproto.org) (and is created by the same author), but designed to play nice in the web stack. That means:
4: * Like Cap'n Proto, it is an object-capability protocol. ("Cap'n" is short for "capabilities and".) We'll get into this more below, but it's incredibly powerful.
5: * Unlike Cap'n Proto, Cap'n Web has no schemas. In fact, it has almost no boilerplate whatsoever. This means it works more like the [JavaScript-native RPC system in Cloudflare Workers](https://blog.cloudflare.com/javascript-native-rpc/).
6: * That said, it integrates nicely with TypeScript.
7: * Also unlike Cap'n Proto, Cap'n Web's underlying serialization is human-readable. In fact, it's just JSON, with a little pre-/post-processing.
8: * It works over HTTP, WebSocket, and postMessage() out-of-the-box, with the ability to extend it to other transports easily.
9: * It works in all major browsers, Cloudflare Workers, Node.js, and other modern JavaScript runtimes.
10: The whole thing compresses (minify+gzip) to under 10kB with no dependencies.
11: 
12: Cap'n Web is more expressive than almost every other RPC system, because it implements an object-capability RPC model. That means it:
13: * Supports bidirectional calling. The client can call the server, and the server can also call the client.
14: * Supports passing functions by reference: If you pass a function over RPC, the recipient receives a "stub". When they call the stub, they actually make an RPC back to you, invoking the function where it was created. This is how bidirectional calling happens: the client passes a callback to the server, and then the server can call it later.
15: * Similarly, supports passing objects by reference: If a class extends the special marker type `RpcTarget`, then instances of that class are passed by reference, with method calls callin...

<path>/nvme/code/capnweb/protocol.md</path>
<type>file</type>
<content>1: # RPC Protocol
2: 
3: ## Serialization
4: 
5: The protocol uses JSON as its basic serialization, with a preprocessing step to support non-JSON types.
6: 
7: Why not a binary format? While the author is a big fan of optimized binary protocols in other contexts, it cannot be denied that in a browser, JSON has big advantages. Being built-in to the browser gives it a leg up in performance, code size, and developer tooling.
8: 
9: Non-JSON types are encoded using arrays. The first element of the array contains a string type code, and the remaining elements contain the parameters needed to construct that type. For example, a `Date` might be encoded as:
10: 
11: ```
12: ["date", 1749342170815]
13: ```
14: 
15: To encode an array, the array must be wrapped in a second layer of array to create an array expression:
16: 
17: ```
18: [["just", "an", "array"]]
19: ```
20: 
21: ## Client vs. Server
22: 
23: The protocol does not have a "client" or a "server"; it is fully bidirectional. Either side can call interfaces exported by the other.
24: 
25: With that said, for documentation purposes, we often use the words "client" and "server" when describing specific interactions, in order to make the language easier to understand. The word "client" generally refers to the caller of an RPC, or the importer of a stub. The word "server" refers to the callee, or the exporter. This is merely a convention to make explanations more natural.
26: 
27: ## Transport and Framing
28: 
29: The protocol operates on a bidirectional stream of discrete messages. Each message is a single JSON value (typically an array). The protocol does not define how messages are framed on the wire; this is the responsibility of the transport layer.
30: 
31: For transports that natively provide message framing (e.g. WebSocket or MessagePort), each transport-level message corresponds to exactly one RPC message.
32: 
33: The built-in HTTP transport...

src/map.ts:15:    | ["remap", number, PropertyPath, ["import", number][], MapInstruction[]]
src/map.ts:68:                  this.context.captures.map(cap => ["import", cap]),
src/rpc.ts:655:        return ["import", importId];
src/serialize.ts:341:            return ["import", importId];

336-              return ["pipeline", importId, pathIfPromise];
337-            } else {
338-              return ["pipeline", importId];
339-            }
340-          } else {
341:            return ["import", importId];
342-          }
343-        }
344-
345-        if (pathIfPromise) {
346-          hook = hook.get(pathIfPromise);

cat: src/protocol.ts: No such file or directory

batch.ts
core.ts
index-workers.ts
index.ts
inject-workers-module.ts
map.ts
messageport.ts
rpc.ts
serialize.ts
streams.ts
symbols.ts
types.d.ts
websocket.ts

// Copyright (c) 2025 Cloudflare, Inc.
// Licensed under the MIT license found in the LICENSE.txt file or at:
//     https://opensource.org/license/mit

// This file borrows heavily from `types/defines/rpc.d.ts` in workerd.

// Branded types for identifying `WorkerEntrypoint`/`DurableObject`/`Target`s.
// TypeScript uses *structural* typing meaning anything with the same shape as type `T` is a `T`.
// For the classes exported by `cloudflare:workers` we want *nominal* typing (i.e. we only want to
// accept `WorkerEntrypoint` from `cloudflare:workers`, not any other class with the same shape)
export const __RPC_STUB_BRAND: '__RPC_STUB_BRAND';
export const __RPC_TARGET_BRAND: '__RPC_TARGET_BRAND';
export interface RpcTargetBranded {
  [__RPC_TARGET_BRAND]: never;
}

// Types that can be used through `Stub`s
export type Stubable = RpcTargetBranded | ((...args: any[]) => any);

// Types that can be passed over RPC
// The reason for using a generic type here is to build a serializable subset of structured
//   cloneable composite types. This allows types defined with the "interface" keyword to pass the
//   serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
export type RpcCompatible<T> =
  // Structured cloneables
  | BaseType
  // Structured cloneable composites
  | Map<
      T extends Map<infer U, unknown> ? RpcCompatible<U> : never,
      T extends Map<unknown, infer U> ? RpcCompatible<U> : never
    >
  | Set<T extends Set<infer U> ? RpcCompatible<U> : never>
  | Array<T extends Array<infer U> ? RpcCompatible<U> : never>
  | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never>
  | {
      [K in keyof T as K extends string | number ? K : never]: RpcCompatible<T[K]>;
    }
  | Promise<T extends Promise<infer U> ? RpcCompatible<U> : never>
  // Special types
  | Stub<Stubable>
  // Serialized as stubs, see `Stubify`
  | Stubable;

// Base type for all RPC stubs, including common memory management methods.
...

650-    }
651-
652-    let devaluedCaptures = captures.map(hook => {
653-      let importId = this.getImport(hook);
654-      if (importId !== undefined) {
655:        return ["import", importId];
656-      } else {
657-        return ["export", this.exportStub(hook)];
658-      }
659-    });
660-

326-        if (!this.source) {
327-          throw new Error("Can't serialize RPC stubs in this context.");
328-        }
329-
330-        let {hook, pathIfPromise} = unwrapStubAndPath(<RpcStub>value);
331-        let importId = this.exporter.getImport(hook);
332-        if (importId !== undefined) {
333-          if (pathIfPromise) {
334-            // It's a promise pointing back to the peer, so we are doing pipelining here.
335-            if (pathIfPromise.length > 0) {
336-              return ["pipeline", importId, pathIfPromise];
337-            } else {
338-              return ["pipeline", importId];
339-            }
340-          } else {
341:            return ["import", importId];
342-          }
343-        }
344-
345-        if (pathIfPromise) {
346-          hook = hook.get(pathIfPromise);
347-        } else {
348-          hook = hook.dup();
349-        }
350-
351-        return this.devaluateHook(pathIfPromise ? "promise" : "export", hook);
352-      }
353-
354-      case "function":
355-      case "rpc-target": {
356-        if (!this.source) {
--
619-          if (init.webSocket) {
620-            // `response.webSocket` is a Cloudflare Workers extension. Not (yet?) supported for
621-            // serialization.
622-            throw new TypeError("Can't deserialize a Response containing a webSocket.");
623-          }
624-
625-          // Type-check `headers` is an array because the constructor allows multiple
626-          // representations and we don't want to allow the others.
627-          if (init.headers && !(init.headers instanceof Array)) {
628-            throw new TypeError("Request headers must be serialized as an array of pairs.");
629-          }
630-
631-          return new Response(body as BodyInit | null, init as ResponseInit);
632-        }
633-
634:        case "import":
635-        case "pipeline": {
636:          // It's an "import" from the perspective of the sender, so it's an export from our
637-          // side. In ...

Wrote file successfully.