@runtypelabs/cloudflare-agents 0.1.1

package/dist/index.mjs

@@ -0,0 +1,339 @@
+import { n as operationSpanId, t as createRunIdentity } from "./chunk-BuRpWjxB.mjs";
+//#region src/content.ts
+const MAX_CONTENT_BYTES = 32768;
+function diagnose$1(policy, code) {
+	try {
+		policy.onDiagnostic?.(code);
+	} catch {
+		return;
+	}
+}
+function isEnabled(policy, kind) {
+	if (kind === "instructions") return policy.instructions ?? policy.messages ?? false;
+	if (kind === "error") return policy.errors ?? false;
+	return policy[kind] ?? false;
+}
+/** Applies privacy policy before a content value can enter telemetry storage. */
+function captureContent(policy, kind, value) {
+	if (!isEnabled(policy, kind) || value === void 0) return void 0;
+	const limit = policy.maxBytes ?? MAX_CONTENT_BYTES;
+	if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_CONTENT_BYTES) {
+		diagnose$1(policy, "content_invalid");
+		return;
+	}
+	let detached;
+	try {
+		detached = JSON.parse(JSON.stringify(value));
+	} catch {
+		diagnose$1(policy, "content_invalid");
+		return;
+	}
+	let redacted;
+	try {
+		redacted = policy.redact ? policy.redact(kind, detached) : detached;
+	} catch {
+		diagnose$1(policy, "content_redaction_failed");
+		return;
+	}
+	if (redacted === void 0) return void 0;
+	try {
+		const serialized = JSON.stringify(redacted);
+		if (serialized === void 0) {
+			diagnose$1(policy, "content_invalid");
+			return;
+		}
+		if (new TextEncoder().encode(serialized).byteLength > limit) {
+			diagnose$1(policy, "content_too_large");
+			return;
+		}
+		return JSON.parse(serialized);
+	} catch {
+		diagnose$1(policy, "content_invalid");
+		return;
+	}
+}
+//#endregion
+//#region src/observer.ts
+/** Adds bounded observation callbacks without reading or replacing the response stream. */
+async function observeStreamTextOptions(options, observation) {
+	const destination = observation.observer;
+	let deliveryFailed = false;
+	observation = {
+		...observation,
+		turn: { ...observation.turn },
+		observer: {
+			onDiagnostic: destination.onDiagnostic,
+			async emit(event) {
+				const terminal = event.kind === "finished" || event.kind === "aborted" || event.kind === "errored";
+				const outgoing = deliveryFailed && terminal ? {
+					kind: "incomplete",
+					turn: event.turn,
+					reason: "observation_delivery_failed"
+				} : event;
+				try {
+					await destination.emit(outgoing);
+				} catch (error) {
+					deliveryFailed = true;
+					throw error;
+				}
+			}
+		}
+	};
+	await emit(observation.observer, {
+		kind: "accepted",
+		turn: observation.turn
+	});
+	if (observation.turn.continuation) await emit(observation.observer, {
+		kind: "unsupported",
+		turn: observation.turn,
+		reason: "continuation"
+	});
+	const pendingToolCalls = /* @__PURE__ */ new Set();
+	const completedServerToolCalls = /* @__PURE__ */ new Set();
+	let lastToolError;
+	return {
+		...options,
+		experimental_onStart: options.experimental_onStart,
+		experimental_onStepStart: wrap(options.experimental_onStepStart, async (event) => {
+			await emitModelInput(observation, event, event.stepNumber);
+		}),
+		experimental_onToolCallStart: wrap(options.experimental_onToolCallStart, async (event) => {
+			await emit(observation.observer, {
+				kind: "tool_started",
+				turn: observation.turn,
+				stepNumber: event.stepNumber,
+				...model(event.model) ? { model: model(event.model) } : {},
+				toolCall: toolCall(observation, event.toolCall)
+			});
+		}),
+		experimental_onToolCallFinish: wrap(options.experimental_onToolCallFinish, async (event) => {
+			const id = toolCallId(event.toolCall);
+			if (id) completedServerToolCalls.add(id);
+			const output = event.success ? captureContent(observation.content, "tools", event.output) : void 0;
+			const error = event.success ? void 0 : captureError(observation.content, event.error);
+			if (!event.success) lastToolError = error;
+			const outcome = event.success ? output === void 0 ? {} : { output } : error === void 0 ? {} : { error };
+			await emit(observation.observer, {
+				kind: "tool_finished",
+				turn: observation.turn,
+				stepNumber: event.stepNumber,
+				...model(event.model) ? { model: model(event.model) } : {},
+				toolCall: toolCall(observation, event.toolCall),
+				durationMs: boundedDuration(event.durationMs),
+				success: event.success,
+				...outcome
+			});
+		}),
+		onStepFinish: wrap(options.onStepFinish, async (event) => {
+			updatePendingToolCalls(pendingToolCalls, event);
+			for (const id of completedServerToolCalls) pendingToolCalls.delete(id);
+			await emit(observation.observer, modelStep(observation, event));
+		}),
+		onFinish: wrap(options.onFinish, async (event) => {
+			if (observation.turn.continuation) return;
+			for (const id of completedServerToolCalls) pendingToolCalls.delete(id);
+			const terminalToolError = event.finishReason === "tool-calls" && event.content.some((part) => part.type === "tool-error");
+			if (event.finishReason === "error" || terminalToolError) {
+				await emit(observation.observer, {
+					kind: "errored",
+					turn: observation.turn,
+					...lastToolError === void 0 ? {} : { error: lastToolError }
+				});
+				return;
+			}
+			if (pendingToolCalls.size > 0) {
+				await emit(observation.observer, {
+					kind: "unsupported",
+					turn: observation.turn,
+					reason: "unresolved_tool_calls"
+				});
+				return;
+			}
+			await emit(observation.observer, {
+				kind: "finished",
+				turn: observation.turn
+			});
+		}),
+		onAbort: wrap(options.onAbort, async () => {
+			await emit(observation.observer, {
+				kind: "aborted",
+				turn: observation.turn
+			});
+		}),
+		onError: wrap(options.onError, async (event) => {
+			const error = captureError(observation.content, event.error);
+			await emit(observation.observer, {
+				kind: "errored",
+				turn: observation.turn,
+				...error === void 0 ? {} : { error }
+			});
+		})
+	};
+}
+function wrap(existing, observe) {
+	return async (event) => {
+		await existing?.(event);
+		try {
+			await observe(event);
+		} catch {
+			return;
+		}
+	};
+}
+async function emit(observer, event) {
+	try {
+		await observer.emit(event);
+	} catch {
+		diagnose(observer, "observer_emit_failed");
+	}
+}
+function diagnose(observer, code) {
+	try {
+		observer.onDiagnostic?.(code);
+	} catch {
+		return;
+	}
+}
+function emitModelInput(observation, event, stepNumber) {
+	const system = captureContent(observation.content, "instructions", event.system);
+	const messages = captureMessages(observation.content, event.messages);
+	return emit(observation.observer, {
+		kind: "model_input",
+		turn: observation.turn,
+		stepNumber,
+		model: model(event.model) ?? {
+			provider: "",
+			modelId: ""
+		},
+		...system === void 0 ? {} : { system },
+		...messages === void 0 ? {} : { messages }
+	});
+}
+function modelStep(observation, event) {
+	const output = captureContent(observation.content, "messages", event.text);
+	const toolCalls = toolsEnabled(observation.content) ? captureContent(observation.content, "tools", event.toolCalls) : void 0;
+	const toolResults = toolsEnabled(observation.content) ? captureContent(observation.content, "tools", event.toolResults) : void 0;
+	const finishReason = boundedString(event.finishReason);
+	return {
+		kind: "model_step",
+		turn: observation.turn,
+		stepNumber: event.stepNumber,
+		model: model(event.model) ?? {
+			provider: "",
+			modelId: ""
+		},
+		...output === void 0 ? {} : { output },
+		...toolCalls === void 0 ? {} : { toolCalls },
+		...toolResults === void 0 ? {} : { toolResults },
+		...finishReason === void 0 ? {} : { finishReason },
+		usage: usage(event.usage)
+	};
+}
+function updatePendingToolCalls(pendingToolCalls, event) {
+	for (const call of event.toolCalls) {
+		const id = toolCallId(call);
+		if (id) pendingToolCalls.add(id);
+	}
+	for (const result of event.toolResults) {
+		const id = toolCallId(result);
+		if (id) pendingToolCalls.delete(id);
+	}
+}
+function toolCallId(value) {
+	if (!value || typeof value !== "object") return void 0;
+	return boundedString(value.toolCallId);
+}
+function captureMessages(policy, messages) {
+	if (!Array.isArray(messages)) return captureContent(policy, "messages", messages);
+	const captured = messages.flatMap((message) => {
+		const value = captureMessage(policy, message);
+		return value === void 0 ? [] : [value];
+	});
+	return captured.length === 0 ? void 0 : captured;
+}
+function captureMessage(policy, message) {
+	const kind = messageKind(message);
+	if (kind !== "messages") return captureContent(policy, kind, message);
+	if (!message || typeof message !== "object") return captureContent(policy, "messages", message);
+	const content = message.content;
+	if (!Array.isArray(content)) return captureContent(policy, "messages", message);
+	const capturedContent = content.flatMap((part) => {
+		const value = captureContent(policy, partKind(part), part);
+		return value === void 0 ? [] : [value];
+	});
+	if (capturedContent.length === 0) return void 0;
+	return captureContent(policy, "messages", {
+		...message,
+		content: capturedContent
+	});
+}
+function messageKind(message) {
+	if (!message || typeof message !== "object") return "messages";
+	const role = message.role;
+	if (role === "system" || role === "developer") return "instructions";
+	return role === "tool" ? "tools" : "messages";
+}
+function partKind(part) {
+	if (!part || typeof part !== "object") return "messages";
+	const type = part.type;
+	return typeof type === "string" && type.startsWith("tool-") ? "tools" : "messages";
+}
+function toolsEnabled(policy) {
+	return policy.tools === true;
+}
+function toolCall(observation, value) {
+	if (!value || typeof value !== "object") {
+		diagnose(observation.observer, "invalid_sdk_event");
+		return {};
+	}
+	const call = value;
+	const toolCallId = boundedString(call.toolCallId);
+	const toolName = boundedString(call.toolName);
+	const input = captureContent(observation.content, "tools", call.input);
+	return {
+		...toolCallId === void 0 ? {} : { toolCallId },
+		...toolName === void 0 ? {} : { toolName },
+		...input === void 0 ? {} : { input }
+	};
+}
+function model(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const candidate = value;
+	const provider = boundedString(candidate.provider);
+	const modelId = boundedString(candidate.modelId);
+	return provider && modelId ? {
+		provider,
+		modelId
+	} : void 0;
+}
+function captureError(policy, error) {
+	if (error instanceof Error) return captureContent(policy, "error", {
+		name: error.name,
+		message: error.message
+	});
+	return captureContent(policy, "error", error);
+}
+function boundedString(value) {
+	return typeof value === "string" && value.length > 0 && value.length <= 512 ? value : void 0;
+}
+function boundedDuration(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+function usage(value) {
+	if (!value || typeof value !== "object") return {};
+	return Object.fromEntries(Object.entries(value).filter(([, amount]) => typeof amount === "number" && Number.isFinite(amount) && amount >= 0));
+}
+//#endregion
+//#region src/durable-observer.ts
+/** Bridges a companion Durable Object receipt to the observer's delivery diagnostic. */
+function createDurableObserver(sink, onDiagnostic) {
+	return {
+		onDiagnostic,
+		async emit(observation) {
+			if (!(await sink.observe(observation)).accepted) throw new Error("Durable adapter observation was not accepted");
+		}
+	};
+}
+//#endregion
+export { captureContent, createDurableObserver, createRunIdentity, observeStreamTextOptions, operationSpanId };
+

package/dist/observer-DnEMHl8z.d.cts

@@ -0,0 +1,121 @@
+import { streamText } from "ai";
+//#region src/identity.d.ts
+interface SubmissionIdentity {
+  agentId: string;
+  submissionId: string;
+  conversationId: string;
+}
+interface RunIdentity extends SubmissionIdentity {
+  traceId: string;
+  rootSpanId: string;
+}
+/** Stable producer identity, independent of native traces and export partitioning. */
+declare function createRunIdentity(input: SubmissionIdentity): Promise<RunIdentity>;
+/** The same operation is encoded with the same span ID on every delivery attempt. */
+declare function operationSpanId(traceId: string, operationId: string): Promise<string>;
+//#endregion
+//#region src/content.d.ts
+type ContentKind = 'messages' | 'instructions' | 'tools' | 'error';
+type CapturedJson = null | boolean | number | string | CapturedJson[] | {
+  [key: string]: CapturedJson;
+};
+type ContentDiagnostic = 'content_invalid' | 'content_redaction_failed' | 'content_too_large';
+interface ContentPolicy {
+  messages?: boolean;
+  /** Instructions follow message capture unless explicitly disabled. */
+  instructions?: boolean;
+  tools?: boolean;
+  errors?: boolean;
+  /** Maximum UTF-8 bytes per captured content field, capped at 32 KiB. */
+  maxBytes?: number;
+  /** Receives a detached copy. Return undefined to omit the field. */
+  redact?: (kind: ContentKind, value: CapturedJson) => CapturedJson | undefined;
+  onDiagnostic?: (code: ContentDiagnostic) => void;
+}
+/** Applies privacy policy before a content value can enter telemetry storage. */
+declare function captureContent(policy: ContentPolicy, kind: ContentKind, value: unknown): CapturedJson | undefined;
+//#endregion
+//#region src/observer.d.ts
+interface AdapterTurn {
+  submissionId: string;
+  conversationId: string;
+  exchangeId: string;
+  continuation: boolean;
+}
+type ObserverDiagnostic = 'observer_emit_failed' | 'invalid_sdk_event';
+interface AdapterObserver {
+  emit(observation: AdapterObservation): void | Promise<void>;
+  onDiagnostic?: (code: ObserverDiagnostic) => void;
+}
+interface AdapterObservationBase {
+  turn: AdapterTurn;
+}
+interface AdapterAcceptedObservation extends AdapterObservationBase {
+  kind: 'accepted';
+}
+interface AdapterModelInputObservation extends AdapterObservationBase {
+  kind: 'model_input';
+  stepNumber: number | undefined;
+  model: AdapterModel;
+  system?: CapturedJson;
+  messages?: CapturedJson;
+}
+interface AdapterModelStepObservation extends AdapterObservationBase {
+  kind: 'model_step';
+  stepNumber: number;
+  model: AdapterModel;
+  output?: CapturedJson;
+  toolCalls?: CapturedJson;
+  toolResults?: CapturedJson;
+  finishReason?: string;
+  usage: Record<string, number>;
+}
+interface AdapterToolStartedObservation extends AdapterObservationBase {
+  kind: 'tool_started';
+  stepNumber: number | undefined;
+  model?: AdapterModel;
+  toolCall: AdapterToolCall;
+}
+interface AdapterToolFinishedObservation extends AdapterObservationBase {
+  kind: 'tool_finished';
+  stepNumber: number | undefined;
+  model?: AdapterModel;
+  toolCall: AdapterToolCall;
+  durationMs: number;
+  success: boolean;
+  output?: CapturedJson;
+  error?: CapturedJson;
+}
+interface AdapterTerminalObservation extends AdapterObservationBase {
+  kind: 'finished' | 'aborted' | 'errored';
+  error?: CapturedJson;
+}
+interface AdapterUnsupportedObservation extends AdapterObservationBase {
+  kind: 'unsupported';
+  reason: 'continuation' | 'unresolved_tool_calls';
+}
+interface AdapterIncompleteObservation extends AdapterObservationBase {
+  kind: 'incomplete';
+  reason: 'observation_delivery_failed';
+}
+type AdapterObservation = AdapterAcceptedObservation | AdapterModelInputObservation | AdapterModelStepObservation | AdapterToolStartedObservation | AdapterToolFinishedObservation | AdapterTerminalObservation | AdapterUnsupportedObservation | AdapterIncompleteObservation;
+interface AdapterModel {
+  provider: string;
+  modelId: string;
+}
+interface AdapterToolCall {
+  toolCallId?: string;
+  toolName?: string;
+  input?: CapturedJson;
+}
+type StreamTextOptions = Parameters<typeof streamText>[0];
+interface ObserveStreamTextOptions {
+  content: ContentPolicy;
+  observer: AdapterObserver;
+  turn: AdapterTurn;
+}
+/** Adds bounded observation callbacks without reading or replacing the response stream. */
+declare function observeStreamTextOptions<Options extends StreamTextOptions>(options: Options, observation: ObserveStreamTextOptions): Promise<Options>;
+//#endregion
+export { operationSpanId as _, AdapterToolStartedObservation as a, observeStreamTextOptions as c, ContentKind as d, ContentPolicy as f, createRunIdentity as g, SubmissionIdentity as h, AdapterObserver as i, CapturedJson as l, RunIdentity as m, AdapterModelStepObservation as n, AdapterTurn as o, captureContent as p, AdapterObservation as r, ObserveStreamTextOptions as s, AdapterModelInputObservation as t, ContentDiagnostic as u };
+export {}

package/dist/observer-DnEMHl8z.d.ts

@@ -0,0 +1,121 @@
+import { streamText } from "ai";
+//#region src/identity.d.ts
+interface SubmissionIdentity {
+  agentId: string;
+  submissionId: string;
+  conversationId: string;
+}
+interface RunIdentity extends SubmissionIdentity {
+  traceId: string;
+  rootSpanId: string;
+}
+/** Stable producer identity, independent of native traces and export partitioning. */
+declare function createRunIdentity(input: SubmissionIdentity): Promise<RunIdentity>;
+/** The same operation is encoded with the same span ID on every delivery attempt. */
+declare function operationSpanId(traceId: string, operationId: string): Promise<string>;
+//#endregion
+//#region src/content.d.ts
+type ContentKind = 'messages' | 'instructions' | 'tools' | 'error';
+type CapturedJson = null | boolean | number | string | CapturedJson[] | {
+  [key: string]: CapturedJson;
+};
+type ContentDiagnostic = 'content_invalid' | 'content_redaction_failed' | 'content_too_large';
+interface ContentPolicy {
+  messages?: boolean;
+  /** Instructions follow message capture unless explicitly disabled. */
+  instructions?: boolean;
+  tools?: boolean;
+  errors?: boolean;
+  /** Maximum UTF-8 bytes per captured content field, capped at 32 KiB. */
+  maxBytes?: number;
+  /** Receives a detached copy. Return undefined to omit the field. */
+  redact?: (kind: ContentKind, value: CapturedJson) => CapturedJson | undefined;
+  onDiagnostic?: (code: ContentDiagnostic) => void;
+}
+/** Applies privacy policy before a content value can enter telemetry storage. */
+declare function captureContent(policy: ContentPolicy, kind: ContentKind, value: unknown): CapturedJson | undefined;
+//#endregion
+//#region src/observer.d.ts
+interface AdapterTurn {
+  submissionId: string;
+  conversationId: string;
+  exchangeId: string;
+  continuation: boolean;
+}
+type ObserverDiagnostic = 'observer_emit_failed' | 'invalid_sdk_event';
+interface AdapterObserver {
+  emit(observation: AdapterObservation): void | Promise<void>;
+  onDiagnostic?: (code: ObserverDiagnostic) => void;
+}
+interface AdapterObservationBase {
+  turn: AdapterTurn;
+}
+interface AdapterAcceptedObservation extends AdapterObservationBase {
+  kind: 'accepted';
+}
+interface AdapterModelInputObservation extends AdapterObservationBase {
+  kind: 'model_input';
+  stepNumber: number | undefined;
+  model: AdapterModel;
+  system?: CapturedJson;
+  messages?: CapturedJson;
+}
+interface AdapterModelStepObservation extends AdapterObservationBase {
+  kind: 'model_step';
+  stepNumber: number;
+  model: AdapterModel;
+  output?: CapturedJson;
+  toolCalls?: CapturedJson;
+  toolResults?: CapturedJson;
+  finishReason?: string;
+  usage: Record<string, number>;
+}
+interface AdapterToolStartedObservation extends AdapterObservationBase {
+  kind: 'tool_started';
+  stepNumber: number | undefined;
+  model?: AdapterModel;
+  toolCall: AdapterToolCall;
+}
+interface AdapterToolFinishedObservation extends AdapterObservationBase {
+  kind: 'tool_finished';
+  stepNumber: number | undefined;
+  model?: AdapterModel;
+  toolCall: AdapterToolCall;
+  durationMs: number;
+  success: boolean;
+  output?: CapturedJson;
+  error?: CapturedJson;
+}
+interface AdapterTerminalObservation extends AdapterObservationBase {
+  kind: 'finished' | 'aborted' | 'errored';
+  error?: CapturedJson;
+}
+interface AdapterUnsupportedObservation extends AdapterObservationBase {
+  kind: 'unsupported';
+  reason: 'continuation' | 'unresolved_tool_calls';
+}
+interface AdapterIncompleteObservation extends AdapterObservationBase {
+  kind: 'incomplete';
+  reason: 'observation_delivery_failed';
+}
+type AdapterObservation = AdapterAcceptedObservation | AdapterModelInputObservation | AdapterModelStepObservation | AdapterToolStartedObservation | AdapterToolFinishedObservation | AdapterTerminalObservation | AdapterUnsupportedObservation | AdapterIncompleteObservation;
+interface AdapterModel {
+  provider: string;
+  modelId: string;
+}
+interface AdapterToolCall {
+  toolCallId?: string;
+  toolName?: string;
+  input?: CapturedJson;
+}
+type StreamTextOptions = Parameters<typeof streamText>[0];
+interface ObserveStreamTextOptions {
+  content: ContentPolicy;
+  observer: AdapterObserver;
+  turn: AdapterTurn;
+}
+/** Adds bounded observation callbacks without reading or replacing the response stream. */
+declare function observeStreamTextOptions<Options extends StreamTextOptions>(options: Options, observation: ObserveStreamTextOptions): Promise<Options>;
+//#endregion
+export { operationSpanId as _, AdapterToolStartedObservation as a, observeStreamTextOptions as c, ContentKind as d, ContentPolicy as f, createRunIdentity as g, SubmissionIdentity as h, AdapterObserver as i, CapturedJson as l, RunIdentity as m, AdapterModelStepObservation as n, AdapterTurn as o, captureContent as p, AdapterObservation as r, ObserveStreamTextOptions as s, AdapterModelInputObservation as t, ContentDiagnostic as u };
+export {}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@runtypelabs/cloudflare-agents",
+  "version": "0.1.1",
+  "description": "Durable application telemetry for Cloudflare Agents SDK runs in Runtype.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./durable-object": {
+      "types": "./dist/durable-object.d.ts",
+      "import": "./dist/durable-object.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260804.1",
+    "ai": "6.0.277",
+    "tsdown": "^0.23.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.2"
+  },
+  "peerDependencies": {
+    "ai": "6.0.277"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runtypelabs/core",
+    "directory": "packages/cloudflare-agents"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "eslint . --max-warnings 0"
+  }
+}