@moldea.ai/adapter-cloudflare-agents 2.0.1 → 3.0.1

package/README.md

@@ -8,10 +8,10 @@ The package implements the official `cloudflare-agents` runtime adapter for `@mo
 
 ## Supported targets
 
-Version `2.0.1` supports:
+Version `3.0.1` supports:
 
 - Repository Format version `1`
-- `@moldea.ai/core ^3.0.0`
+- `@moldea.ai/core ^4.0.0`
 - TypeScript ESM `.ts`, `.tsx`, and `.mts` source
 - `@cloudflare/think >=0.16.0`, `agents >=0.21.0`, and `ai >=7.0.0`
 - `@cloudflare/ai-chat >=0.10.2`, `agents >=0.21.0`, and `ai >=7.0.0`
@@ -71,6 +71,8 @@ Evidence is source-grounded, references existing repository files, and contains
 
 ## Documentation
 
+These guides are included in the installed package. Open only the page relevant to your task.
+
 - [Adapter contract](docs/index.md)
 - [Verified targets](docs/verified-targets.md)
 - [Evidence and diagnostics](docs/evidence-and-diagnostics.md)

package/docs/evidence-and-diagnostics.md

@@ -0,0 +1,13 @@
+---
+title: Evidence and diagnostics
+description: Source-grounded observations and stable Cloudflare adapter failures.
+order: 20
+---
+
+# Evidence and diagnostics
+
+Package evidence records exact dependency declarations and whether each declaration is supported or ambiguous for the selected target. Unsupported disjoint ranges produce `CLOUDFLARE_AGENTS_RUNTIME_VERSION_UNSUPPORTED` and suppress target-derived evidence.
+
+`agent-definition` identifies a supported exported class. `runtime-pattern` identifies direct AI SDK generation in `AIChatAgent`; Think does not emit it. `instruction-loader`, `schema`, and `tool-registration` require exact manifest binding identity. `handoff-registration` requires an active `agentTool` in a closed tools map, a unique registered target class, and an exact routing-description match against the target agent's handoff description or description fallback.
+
+The package README is the canonical package diagnostic catalog. Dynamic or unsupported forms yield partial or no evidence rather than guessed relationships. Unsupported class initialization preserves package and language observations but suppresses all class method-derived results.

package/docs/index.md

@@ -0,0 +1,13 @@
+---
+title: Cloudflare Agents adapter
+description: Package contract, integration model, and public surface.
+order: 0
+---
+
+# Cloudflare Agents adapter
+
+`@moldea.ai/adapter-cloudflare-agents` is the official source-neutral adapter for the `cloudflare-agents` runtime id. It implements `IRuntimeAdapter`, supports Repository Format version `1`, and exposes only `cloudflareAgentsAdapter`.
+
+The adapter inspects TypeScript source through the repository reader supplied by Core. It does not execute source, load Cloudflare packages, inspect `node_modules`, use credentials, or make network requests. Runtime applications register the singleton with `createCore({ adapters: [cloudflareAgentsAdapter] })`; the local CLI registers active official adapters automatically.
+
+The [Runtime Compatibility Matrix](https://packages.moldea.ai/compatibility/) is authoritative. This documentation explains the package behavior but does not expand the verified target boundary.

package/docs/limitations.md

@@ -0,0 +1,21 @@
+---
+title: Boundaries and limitations
+description: Unsupported Cloudflare surfaces, source forms, and the adapter security boundary.
+order: 30
+---
+
+# Boundaries and limitations
+
+The current verified targets do not claim support for:
+
+- JavaScript, Python, CommonJS, default imports, namespace imports, or source outside TypeScript ESM
+- the bare `Agent` class, custom harnesses, factories, indirect subclasses, re-export graphs, or decorators
+- executable class fields, static blocks, computed member names, generator methods, or non-pass-through constructors
+- dynamic session builders, `onCompaction`, mutable definitions, open tools maps, or channel-provided tool replacement
+- nested generation calls, request variables, `prepareStep` instruction interpretation, or generation APIs other than `generateText` and `streamText`
+- output variants other than `Output.object({ schema })` or any agent input schema
+- dynamic, provider, MCP-generated, or inline tools as manifest registration identities
+- arbitrary compiler resolution, `tsconfig` path aliases, directory indexes, package exports, or general re-export graphs
+- runtime-generated strings, schema-content validation, provider compatibility, model behavior, or actual tool execution
+
+Package detection uses nearest manifests, not lockfiles or installed `node_modules`. Each invocation sees one declared agent, exact same-runtime binding resolution, and only the bounded operations Core supplies through `IRuntimeAdapterRepository`. It receives no complete agent collection, project body index, host path, credential, environment variable, network client, or runtime process.

package/docs/verified-targets.md

@@ -0,0 +1,21 @@
+---
+title: Verified targets
+description: Exact Cloudflare package ranges and statically supported integration patterns.
+order: 10
+---
+
+# Verified targets
+
+## Think 0.16 with AI SDK 7
+
+The `typescript-think-0-16-ai-sdk-7` target requires `@cloudflare/think >=0.16.0`, `agents >=0.21.0`, and `ai >=7.0.0`.
+
+The runtime agent must be a directly exported class extending an exact named `Think` import. Instructions may come from a direct loader call returned by `getSystemPrompt` or from the supported closed `configureSession` chain. Function tools and handoffs must be active in a closed `getTools` map. This target emits no `runtime-pattern` evidence and supports no agent input or output schema binding.
+
+## AIChatAgent 0.10 with AI SDK 7
+
+The `typescript-ai-chat-agent-0-10-ai-sdk-7` target requires `@cloudflare/ai-chat >=0.10.2`, `agents >=0.21.0`, and `ai >=7.0.0`.
+
+The runtime agent must be a directly exported class extending an exact named `AIChatAgent` import. Its supported `onChatMessage(onFinish, options?)` method contains direct `generateText({ ... })` or `streamText({ ... })` calls in its own lexical body. `instructions` takes precedence over `system`; `prepareStep` makes instructions unresolved. Agent output schemas use `Output.object({ schema })`.
+
+Both targets require closed class initialization, named ESM imports, normalized `.ts`, `.tsx`, or `.mts` text, and exact relative ESM binding resolution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldea.ai/adapter-cloudflare-agents",
-  "version": "2.0.1",
+  "version": "3.0.1",
   "description": "Deterministic runtime evidence and diagnostics for Cloudflare Agents integrations.",
   "homepage": "https://github.com/moldea-ai/packages/tree/main/projects/adapter-cloudflare-agents#readme",
   "bugs": {
@@ -18,6 +18,7 @@
   "files": [
     "cover.png",
     "dist",
+    "docs",
     "LICENSE",
     "README.md"
   ],
@@ -33,7 +34,7 @@
     "node": ">=22.11.0"
   },
   "dependencies": {
-    "@moldea.ai/core": "^3.0.0",
+    "@moldea.ai/core": "^4.0.0",
     "@moldea.ai/repository": "^2.0.0",
     "semver": "7.8.5",
     "typescript": "6.0.3"