@moldea.ai/adapter-cloudflare-agents 3.0.0 → 3.0.2

package/README.md

@@ -8,7 +8,7 @@ The package implements the official `cloudflare-agents` runtime adapter for `@mo
 
 ## Supported targets
 
-Version `3.0.0` supports:
+Version `3.0.2` supports:
 
 - Repository Format version `1`
 - `@moldea.ai/core ^4.0.0`
@@ -71,6 +71,10 @@ Evidence is source-grounded, references existing repository files, and contains
 
 ## Documentation
 
+- [Complete binding example](docs/binding-example.md): manifest, canonical instructions, runtime source, and supported schema or routing relationships.
+
+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/binding-example.md

@@ -0,0 +1,239 @@
+---
+title: Binding example
+description: Complete manifest and source files for inspecting cloudflare-agents bindings locally.
+order: 5
+---
+
+# Binding example
+
+Read this example before searching adapter implementation for binding syntax. It is a complete **static inspection** file set, not a deployment starter or a live provider test. The files are checked together through this adapter and Core without installing or executing the target SDK. Keep application setup, credentials, provider model access, tool execution, and deployment configuration separate.
+
+## How the bindings connect
+
+Both exported classes are bound separately. Think connects `getSystemPrompt` and the closed `getTools` map; it has no agent input/output schema evidence. AIChatAgent connects its direct `streamText` call and `Output.object` schema. `agentTool` supplies the exact target routing description. Function tools bind `execute`, `inputSchema`, and `outputSchema`. The Markdown imports require the application's Worker text-module configuration; this is not a deployable Worker scaffold.
+
+Paths below are repository-root-relative logical paths. Keep the canonical instructions as the policy source. General manifest semantics belong to the [Repository Format specification](https://packages.moldea.ai/repository-format/). Use the other local guides for the full supported boundary and limitations; this example does not expand them.
+
+## Files
+
+<!-- example:start -->
+
+### /moldea/moldea.yaml
+
+```yaml
+version: 1
+agents:
+  support:
+    runtime:
+      id: 'cloudflare-agents'
+    bindings:
+      runtimeAgent:
+        path: '/src/agents.ts'
+        symbol: 'SupportAgent'
+      instructionLoader:
+        path: '/src/instructions.ts'
+        symbol: 'loadSupportInstruction'
+    tools:
+      find-order:
+        name: 'find_order'
+        description: 'Finds an order.'
+        implementation:
+          path: '/src/implementations.ts'
+          symbol: 'findOrder'
+        registration:
+          path: '/src/tools.ts'
+          symbol: 'findOrderTool'
+        inputSchema:
+          path: '/src/contracts.ts'
+          symbol: 'FindOrderInputSchema'
+        outputSchema:
+          path: '/src/contracts.ts'
+          symbol: 'FindOrderOutputSchema'
+  summary:
+    runtime:
+      id: 'cloudflare-agents'
+    bindings:
+      runtimeAgent:
+        path: '/src/agents.ts'
+        symbol: 'SummaryAgent'
+      instructionLoader:
+        path: '/src/instructions.ts'
+        symbol: 'loadSummaryInstruction'
+      outputSchema:
+        path: '/src/contracts.ts'
+        symbol: 'SummaryOutputSchema'
+    tools:
+      find-order:
+        name: 'find_order'
+        description: 'Finds an order.'
+        implementation:
+          path: '/src/implementations.ts'
+          symbol: 'findOrder'
+        registration:
+          path: '/src/tools.ts'
+          symbol: 'findOrderTool'
+        inputSchema:
+          path: '/src/contracts.ts'
+          symbol: 'FindOrderInputSchema'
+        outputSchema:
+          path: '/src/contracts.ts'
+          symbol: 'FindOrderOutputSchema'
+```
+
+### /package.json
+
+```json
+{
+  "dependencies": {
+    "@cloudflare/think": "^0.16.0",
+    "@cloudflare/ai-chat": "^0.10.2",
+    "agents": "^0.21.0",
+    "ai": "^7.0.0",
+    "zod": "4.6.4"
+  },
+  "name": "binding-example",
+  "private": true,
+  "type": "module"
+}
+```
+
+### /moldea/project.md
+
+```markdown
+# Fixture project
+```
+
+### /moldea/agents/support/description.md
+
+```markdown
+Supports customers.
+```
+
+### /moldea/agents/support/instruction.md
+
+```markdown
+You are the `support` agent.
+
+Answer from supplied support facts. Do not invent order status or account information.
+```
+
+### /moldea/agents/summary/description.md
+
+```markdown
+Summarizes requests.
+```
+
+### /moldea/agents/summary/handoff-description.md
+
+```markdown
+Summarizes a support request.
+```
+
+### /moldea/agents/summary/instruction.md
+
+```markdown
+You are the `summary` agent.
+
+Summarize the supplied support request without inventing facts.
+```
+
+### /src/contracts.ts
+
+```typescript
+import { z } from 'zod';
+
+// response and tool contracts
+export const SummaryOutputSchema = z.object({ summary: z.string() });
+export const FindOrderInputSchema = z.object({ orderId: z.string() });
+export const FindOrderOutputSchema = z.object({
+  orderId: z.string(),
+  status: z.enum(['shipped', 'not_found']),
+});
+```
+
+### /src/instructions.ts
+
+```typescript
+import supportInstruction from '../moldea/agents/support/instruction.md';
+import summaryInstruction from '../moldea/agents/summary/instruction.md';
+
+/** Loads the canonical support text through the Worker text-module loader. */
+export const loadSupportInstruction = () => supportInstruction;
+/** Loads the canonical summary text through the Worker text-module loader. */
+export const loadSummaryInstruction = () => summaryInstruction;
+```
+
+### /src/implementations.ts
+
+```typescript
+/** Looks up an order in the example's fixed catalog. */
+export const findOrder = async ({ orderId }: { orderId: string }) => ({
+  orderId,
+  status: orderId === 'order-1042' ? ('shipped' as const) : ('not_found' as const),
+});
+```
+
+### /src/tools.ts
+
+```typescript
+import { tool } from 'ai';
+import { FindOrderInputSchema, FindOrderOutputSchema } from './contracts.js';
+import { findOrder } from './implementations.js';
+export const findOrderTool = tool({
+  inputSchema: FindOrderInputSchema,
+  outputSchema: FindOrderOutputSchema,
+  execute: findOrder,
+});
+```
+
+### /src/agents.ts
+
+```typescript
+import { AIChatAgent } from '@cloudflare/ai-chat';
+import { Think } from '@cloudflare/think';
+import { agentTool } from 'agents/agent-tools';
+import { Output, streamText } from 'ai';
+import { SummaryOutputSchema } from './contracts.js';
+import { loadSummaryInstruction, loadSupportInstruction } from './instructions.js';
+import { findOrderTool } from './tools.js';
+
+export class SummaryAgent extends AIChatAgent {
+  onChatMessage(_onFinish: unknown, _options?: unknown) {
+    return streamText({
+      model: 'openai/gpt-5',
+      prompt: 'Summarize this support request.',
+      instructions: loadSummaryInstruction(),
+      output: Output.object({ schema: SummaryOutputSchema }),
+      tools: { find_order: findOrderTool },
+    });
+  }
+}
+
+export const summaryHandoffTool = agentTool(SummaryAgent, {
+  description: 'Summarizes a support request.',
+});
+
+export class SupportAgent extends Think {
+  getSystemPrompt() {
+    return loadSupportInstruction();
+  }
+  getTools() {
+    return { find_order: findOrderTool, summarize: summaryHandoffTool };
+  }
+}
+```
+
+### /src/assets.d.ts
+
+```typescript
+declare module '*.md' {
+  const text: string;
+  export default text;
+}
+```
+
+<!-- example:end -->
+
+## What the check establishes
+
+The integration check reads these exact file blocks, requires positive adapter evidence for the documented relationships, and rejects a broken runtime binding. It does not prove that instructions are followed, that every SDK version accepts these forms, or that the application is ready for production. Continue using the installed adapter diagnostics for your actual source.

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,15 @@
+---
+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.
+
+Start with the [complete binding example](https://packages.moldea.ai/adapters/cloudflare-agents/binding-example/) when connecting runtime source to canonical instructions, schemas, tools, or routing metadata. The same example ships locally as `docs/binding-example.md` in the installed package.

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": "3.0.0",
+  "version": "3.0.2",
   "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"
   ],