@runtypelabs/cloudflare-agents 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Runtype, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# Cloudflare Agents telemetry for Runtype
+
+Application-owned run reporting for ordinary Cloudflare Agents SDK chat turns
+and automatic server-side tools. This package is under beta acceptance testing;
+the framework onboarding chip remains gated until deployed verification passes.
+
+## Integration
+
+Use `observeStreamTextOptions` around the options passed to the application's
+single AI SDK `streamText` call. Return the existing UI response stream without
+adding another consumer. `createDurableObserver` bridges those callbacks to the
+`RuntypeOtlpOutbox` companion Durable Object from the `/durable-object` export.
+
+The companion owns telemetry session state, retry storage, and its alarm. The
+application Agent's alarm is unchanged. Register a separate SQLite-backed DO
+binding and migration for the companion, then configure these server-side
+bindings:
+
+- `RUNTYPE_AGENT_ID`: the destination Runtype agent.
+- `RUNTYPE_API_KEY`: a telemetry-write key stored as a Worker secret.
+- `RUNTYPE_BASE_URL`: the API origin, for example `https://api.runtype-staging.com`.
+
+The application supplies a stable submission ID and separate conversation ID.
+Use a new submission ID for a new user request or explicit rerun. Reuse it for
+transport retries. Reconnecting to observe a response does not start another
+run. Snapshot identity from the accepted application request, rather than
+deriving it from a native Cloudflare trace or the latest conversation message.
+
+The initial compatibility fixture pins `agents@0.22.0`,
+`@cloudflare/ai-chat@0.11.0`, and `ai@6.0.277`. The AI SDK callbacks used here
+include experimental APIs, so this package pins its AI SDK peer dependency.
+Upgrade only with the acceptance fixture and callback-contract tests.
+
+## Content recording
+
+All content categories are disabled by default:
+
+```ts
+const content = {
+  messages: true,
+  instructions: true,
+  tools: true,
+  errors: false,
+}
+```
+
+Instructions follow `messages` when `instructions` is omitted. Set
+`instructions: false` to record conversation messages without system/developer
+instructions. Per-call effective instructions are captured after `prepareStep`,
+including role and order. Provider-internal prompts are not observable.
+
+`tools` controls tool payloads, not structural call identity or duration.
+Error messages are a separate opt-in content boundary. A `redact(kind, value)`
+callback receives a detached JSON value and may return a replacement or
+`undefined` to omit it. Redaction runs before storage or transmission. If it
+throws, the content is omitted and only a bounded diagnostic code is emitted.
+
+Content fields are bounded to 32 KiB of serialized UTF-8 after redaction;
+oversized values are omitted whole. The adapter never stores its API key in
+the outbox payload. Application-supplied identifiers and model/tool names must
+be safe metadata, rather than user content or credentials.
+
+## Lifecycle and delivery
+
+The adapter assigns one OTLP trace to each accepted submission. Ended model and
+tool spans are immutable. A reserved root span is emitted once after an
+observed terminal outcome; it is never sent unfinished and later replaced.
+Pending serialized batches and session changes commit together in the companion
+before a successful observation receipt is returned.
+
+Remote delivery is at least once. A lost acknowledgement retries the same
+serialized facts, allowing Runtype's durable ingest to deduplicate them. Retry
+and expiry diagnostics are available through the companion's `diagnostics()`
+method. Persistence or delivery failure does not intentionally fail the model
+response; provide an observer diagnostic callback and inspect companion health.
+
+Recovery delivers already-persisted telemetry after restart. It cannot resume
+agent execution or recreate a terminal observation that never reached storage.
+An observed cancellation is reported with the canonical `cancelled` stop
+reason. No terminal observation means completion is unknown.
+
+## Beta exclusions
+
+Human approval continuations, client-executed tools, automatic subagent trees,
+native-trace association, and hosted approval/resume controls are unsupported.
+Continuations and unresolved tool calls emit an unsupported observation instead
+of a fabricated successful terminal. Native Cloudflare tracing can remain
+enabled for infrastructure diagnostics; it is not the adapter's export path.
+
+The deployable acceptance kit lives in
+`apps/api/tests/fixtures/cloudflare-adapter-capture` in the Core repository.
+Its package-boundary test uses a packed copy of this package, not source aliases.

package/dist/chunk-BuRpWjxB.mjs

@@ -0,0 +1,42 @@
+//#region src/identity.ts
+function requireIdentity(value) {
+	if (typeof value !== "string" || value.trim().length === 0 || new TextEncoder().encode(value).length > 256) throw new Error("Adapter identity must be a nonempty string of at most 256 UTF-8 bytes");
+}
+function requireOperationId(value) {
+	if (typeof value !== "string" || value.trim().length === 0 || new TextEncoder().encode(value).length > 2053) throw new Error("Adapter operation id must be a nonempty string of at most 2053 UTF-8 bytes");
+}
+async function digest(parts) {
+	const bytes = new TextEncoder().encode(JSON.stringify(parts));
+	const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+	return Array.from(hash, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Stable producer identity, independent of native traces and export partitioning. */
+async function createRunIdentity(input) {
+	requireIdentity(input.agentId);
+	requireIdentity(input.submissionId);
+	requireIdentity(input.conversationId);
+	const traceId = (await digest([
+		"runtype-cloudflare-run-v1",
+		input.agentId,
+		input.submissionId
+	])).slice(0, 32);
+	const rootSpanId = await operationSpanId(traceId, "root");
+	return {
+		...input,
+		traceId,
+		rootSpanId
+	};
+}
+/** The same operation is encoded with the same span ID on every delivery attempt. */
+async function operationSpanId(traceId, operationId) {
+	if (!/^[0-9a-f]{32}$/.test(traceId) || /^0+$/.test(traceId)) throw new Error("Invalid adapter trace identity");
+	requireOperationId(operationId);
+	return (await digest([
+		"runtype-cloudflare-span-v1",
+		traceId,
+		operationId
+	])).slice(0, 16);
+}
+//#endregion
+export { operationSpanId as n, createRunIdentity as t };
+

package/dist/chunk-DBVUQIKL.cjs

@@ -0,0 +1,53 @@
+//#region src/identity.ts
+function requireIdentity(value) {
+	if (typeof value !== "string" || value.trim().length === 0 || new TextEncoder().encode(value).length > 256) throw new Error("Adapter identity must be a nonempty string of at most 256 UTF-8 bytes");
+}
+function requireOperationId(value) {
+	if (typeof value !== "string" || value.trim().length === 0 || new TextEncoder().encode(value).length > 2053) throw new Error("Adapter operation id must be a nonempty string of at most 2053 UTF-8 bytes");
+}
+async function digest(parts) {
+	const bytes = new TextEncoder().encode(JSON.stringify(parts));
+	const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+	return Array.from(hash, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Stable producer identity, independent of native traces and export partitioning. */
+async function createRunIdentity(input) {
+	requireIdentity(input.agentId);
+	requireIdentity(input.submissionId);
+	requireIdentity(input.conversationId);
+	const traceId = (await digest([
+		"runtype-cloudflare-run-v1",
+		input.agentId,
+		input.submissionId
+	])).slice(0, 32);
+	const rootSpanId = await operationSpanId(traceId, "root");
+	return {
+		...input,
+		traceId,
+		rootSpanId
+	};
+}
+/** The same operation is encoded with the same span ID on every delivery attempt. */
+async function operationSpanId(traceId, operationId) {
+	if (!/^[0-9a-f]{32}$/.test(traceId) || /^0+$/.test(traceId)) throw new Error("Invalid adapter trace identity");
+	requireOperationId(operationId);
+	return (await digest([
+		"runtype-cloudflare-span-v1",
+		traceId,
+		operationId
+	])).slice(0, 16);
+}
+//#endregion
+Object.defineProperty(exports, "createRunIdentity", {
+	enumerable: true,
+	get: function() {
+		return createRunIdentity;
+	}
+});
+Object.defineProperty(exports, "operationSpanId", {
+	enumerable: true,
+	get: function() {
+		return operationSpanId;
+	}
+});
+