Informal specification of byte-oriented ReadableStreams as implemented in workerd, derived from — and kept in lockstep with — this suite. The tests are the normative artifact. Value streams live in readable/; the pipeTo/pipeThrough matrix belongs to piping/. The suite COMPLEMENTS WPT (//src/wpt:streams). Probing showed the C++ failures in readable-byte-streams/* root-cause to a few construction and pump divergences plus the close-with-partial and read-min shapes below; the releaseLock→second-reader cluster and the buffer-hazard families are behavior-parity (messages aside).
Dequeue cost stays linear in every internal queue of both streams implementations: buffered chunks, pending reads, pending pull-intos, write requests, the writable controller's chunk queue, and the identity stream's write snapshots. Each test drives one queue to 80k-160k entries (identity: 80k, over a 16x range) and asserts, through helpers.js, that the time grows by at most 4x the linear multiple of a run at 1/8 (identity: 1/16) the size. The ratio is machine-independent; the sizes sit well past the ~20k…
The readable/writable stream halves of connect() TCP sockets under both stream implementations. The tests are the normative artifact. The general Socket surface (startTls, secureTransport, DNS overrides, the connect-handler protocol, HTTP-over-socket) is owned by src/workerd/api/tests/ (http-socket-test, connect-handler-test, starttls-*); this suite owns the STREAMS interaction only. A node sidecar (echo-server.js) runs two TCP servers, their ports delivered through fromEnvironment bindings (STREAMSECHOPORT, STREAMSGREETPORT, plus SIDECAR_HOSTNAME): - echo: echoes every byte; on client half-close, flushes and ends (the client's readable reaches EOF after the…
An informal specification of the two WHATWG queuing strategy classes as implemented in workerd, derived from — and kept in lockstep with — the test suite in this directory. The tests are the normative artifact. Both the C++ implementation (src/workerd/api/streams/readable.h) and the TypeScript implementation (src/perisolate/webstreams/strategies.ts, behind typescriptimplemented_streams) are covered. The WPT streams/queuing-strategies.any.js runs against both implementations; its 12 C++ expectedFailures in src/wpt/streams-test.ts correspond exactly to ledger entries #1–#6 below — the suite pins what the C++ side actually does where…
An informal specification of the JS-backed TransformStream as implemented in workerd, derived from — and kept in lockstep with — the test suite in this directory. The tests are the normative artifact. Both the C++ implementation (src/workerd/api/streams/transform.c++ over standard.c++'s TransformStreamDefaultController) and the TypeScript implementation (behind typescriptimplementedstreams) are covered. The suite COMPLEMENTS WPT (//src/wpt:streams runs transform-streams/ against both implementations). Probing the 30+ C++ expectedFailures showed most narrow to a handful of root causes (below); several WPT "failures" (properties.any's arg counts/prototype-chain, the…
An informal specification of the JS-backed writable stream classes as implemented in workerd, derived from — and kept in lockstep with — the test suite in this directory. The tests are the normative artifact. Both the C++ implementation (src/workerd/api/streams/writable.{h,c++} over standard.c++'s WritableImpl/WritableStreamJsController) and the TypeScript implementation (src/perisolate/webstreams/writable.ts, behind typescriptimplemented_streams) are covered. The suite COMPLEMENTS WPT (//src/wpt:streams runs writable-streams/ against both implementations): behaviors WPT already asserts identically on both sides are not duplicated here. The WPT C++ expectedFailures for writable-streams/ in…
WebCrypto API + Node.js crypto C++ implementations over BoringSSL. crypto.h defines public JSG types (CryptoKey, SubtleCrypto, CryptoKeyUsageSet). impl.h defines internal CryptoKey::Impl base class with per-algorithm static ImportFunc/GenerateFunc dispatch. Algorithm files implement Impl subclasses. OSSLCALL() macro wraps all BoringSSL calls with error translation.
C++ implementations of Node.js built-in modules. Each module = JSG-bound class registered via NODEJS_MODULES(V) macro in node.h. TypeScript counterpart lives in src/node/. Tests in tests/. Naming: <module>-test.js + <module>-test.wd-test; -nodejs- infix when needing compat flags. All tests set compatibilityFlags = ["nodejscompat", "nodejscompatv2", "experimental"]. Network tests (net, tls, http) use sidecar jsbinary targets. fixtures/ has 46 PEM files for crypto. process-stdio tests use shtest with .expectedstdout/.expectedstderr. C++ unit test: buffer-test.c++ via kjtest.
Web Streams API: ReadableStream, WritableStream, TransformStream. See README.md for terse reference (classification, state machines, safety patterns). See docs/streams.md for narrative tutorial. NOTE: C++ code outside this directory does not use jsg::Ref<ReadableStream> or jsg::Ref<WritableStream> directly; it goes through the JsReadableStream / JsWritableStream abstractions in src/workerd/api/js-{readable,writable}-stream.{h,c++}, which hide which stream implementation backs a given stream (and provide JsReadableWritablePair + pipeTo/pipeThrough for abstraction-level pipelines). New C++ consumers of streams should use those abstractions, not the types defined here. Allocating the types defined here…
See README.md for terse reference (type mappings, macro catalog, error catalog). See docs/jsg.md for narrative tutorial. Macro-driven C++/V8 binding layer: declares C++ types as JS-visible resources/structs with automatic type conversion.
Binary + orchestration layer. :workerd is a Rust binary: the :workerd-cli crate (cli/) parses the command line (clap), produces the encoded config (schema files via config-compiler.c++), handles --watch and compile, and runs each serving subcommand (serve, compile, test, fuzzilli, pyodide-lock, make-pyodide-baseline-snapshot) through a run_* function in cli-main.c++. Server (server.c++, ~6K lines) is the god object: parses workerd.capnp config, constructs all service types as nested inner classes, wires sockets/bindings/actors, runs the event loop.
Generates @cloudflare/workers-types .d.ts files from C++ RTTI (via jsg/rtti.capnp) + hand-written defines/*.d.ts. A workerd-hosted Worker extracts RTTI at runtime per compat-date; TypeScript transforms post-process into ambient and importable outputs. CI validates generated-snapshot/ matches. Types in this project come from three layers. Changes must be made in the correct layer: Do not edit files in generated-snapshot/ directly — they are overwritten by just generate-types. If the generated output looks wrong, fix the source layer (C++ RTTI, JSGTSOVERRIDE, or defines/). Types in…
Cloudflare Agents SDK — a framework for building stateful AI agents on Cloudflare Workers. This is a monorepo containing the core SDK packages, examples, guides, sites, and documentation. Some directories have their own AGENTS.md with deeper guidance: Node 24+ required. Uses pnpm workspaces with Nx for task orchestration, caching, and affected detection. Run from the repo root: Run an exampl
A Think agent (@cloudflare/think) that reproduces and fixes cloudflare/agents GitHub issues inside a container-backed @cloudflare/workspace VFS. Anyone trusted on the repo triggers it from an issue comment: e.g. @agent-think reproduce this issue or @agent-think open a PR fixing this. It runs the matching skill (reproduce / open-pr) in a real Linux container and reports back on the issue as the agent-think GitHub App — never impersonating the triggering user. - Replace CI-runner automations (the /repro + /pr Actions shape from…
Reproduce a cloudflare/agents GitHub issue by scaffolding a minimal Agents/Worker project and deploying it to a temporary Cloudflare account, then report findings back on the issue.
Internal design records — the "why" behind decisions in this repo and its libraries. This is the Diátaxis explanation quadrant: architecture rationale, tradeoffs, and alternatives considered. Living documents that describe how a concept or subsystem works right now. Named by topic: state.md, mcp.md, visuals.md. These are the primary entry point — a contributor looking for "how does state work" should open one file and get the full picture. Design docs get updated as the implementation evolves. They always reflect the…
Plain text files in a repository that tell a coding agent how the project works: commands to run, conventions to follow and things to avoid. CLAUDE.md, AGENTS.md, cursor rules and skills are the common kinds.
CLAUDE.md or AGENTS.md?
CLAUDE.md is read by Claude Code. AGENTS.md is an open format that Codex, Cursor and other agents read. Many projects keep one and point the other at it.
What is a skill?
A folder with a SKILL.md that describes one capability, such as filling PDFs or reviewing code. The agent loads it only when the task calls for it.
Can I search my own team's files too?
Your agents already can, over MCP, limited to the files you're allowed to read. Searching them from this page is coming.
CloudflareAGENTS.md