@runtypelabs/openclaw-adapter 0.1.0

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,76 @@
+# Runtype telemetry for OpenClaw
+
+`@runtypelabs/openclaw-adapter` is a native OpenClaw plugin. It observes agent,
+model, and tool hooks and sends one OTLP/JSON trace per completed OpenClaw turn to
+Runtype. It does not host or change the agent.
+
+## Install
+
+Set these environment variables on the OpenClaw Gateway process:
+
+```sh
+RUNTYPE_API_KEY=rt_...           # Runtype key with TELEMETRY:WRITE
+RUNTYPE_AGENT_ID=agent_...       # Saved Runtype agent that owns the run
+RUNTYPE_CAPTURE_CONTENT=true    # Optional; needed for eval case capture
+```
+
+`RUNTYPE_OTLP_URL` optionally overrides the default
+`https://api.runtype.com/v1/otel/v1/traces`. Use it only for a trusted OTLP
+receiver; the adapter sends the telemetry key to that URL.
+
+```sh
+openclaw plugins install @runtypelabs/openclaw-adapter
+openclaw plugins enable runtype
+openclaw config set plugins.entries.runtype.hooks.allowConversationAccess true --strict-json
+openclaw plugins inspect runtype --runtime
+```
+
+Reload the plugin or restart the Gateway if it was running before these changes.
+In an interactive terminal, review OpenClaw's package-source and capability
+prompts before accepting them. Noninteractive installation requires `--force`
+and `--accept-capabilities` after independent review; do not add those flags to
+an unattended setup that has not been reviewed.
+The `allowConversationAccess` grant is required for a non-bundled plugin to
+receive `llm_input`, `llm_output`, and `agent_end` hooks. Review the plugin before
+granting it access to conversations. See [OpenClaw's hook documentation](https://docs.openclaw.ai/plugins/hooks).
+
+For direct `OPENAI_API_KEY` use, pin the model's OpenClaw runtime rather than
+letting the host select its Codex runtime. For example, under
+`agents.defaults.models["openai/gpt-4.1-mini"]`, set
+`"agentRuntime": { "id": "openclaw" }`. This controls OpenClaw model routing;
+it is not an adapter setting.
+
+## What is captured
+
+The adapter emits `invoke_agent` and `chat` spans using GenAI semantic
+conventions, and `execute_tool` spans for completed tool hooks. OpenClaw's
+`llm_input` and `llm_output` hooks describe an entire attempt, not each physical
+provider call, so a `chat` span carries attempt-level model and usage data rather
+than per-call timing or token attribution. Missing attempt usage is not silently
+replaced with zero in the run total. If native provider-call metadata shows a
+fallback across different models, the adapter omits aggregate usage rather
+than pricing it all against one model. Runtype attributes each trace to
+`RUNTYPE_AGENT_ID` and identifies its source as
+`@runtypelabs/openclaw-adapter`.
+
+Prompt, answer, system-instruction, and tool payloads are **off by default**.
+Set `RUNTYPE_CAPTURE_CONTENT=true` to include bounded input/output messages
+for eval case capture. The adapter removes values of environment variables
+whose names indicate API keys, tokens, secrets, passwords, or credentials, and
+omits any content value over 32 KiB after redaction. Review what your agent
+handles before enabling content; this is not a general-purpose DLP system.
+OpenClaw may suppress conversation hooks for privacy-sensitive sessions; the
+plugin does not reconstruct that content from other hooks. Such runs can have
+a structural trace without an eval-capturable transcript.
+
+## Delivery limits
+
+The `agent_end` hook waits up to one second for a pending model or tool
+observation, because OpenClaw can deliver `llm_output` just after `agent_end`.
+It flushes immediately when the pending observation arrives and does not
+invent an output if the grace expires. It then makes one HTTP submission, with
+a 10-second timeout. Telemetry failure does not fail the agent turn. OpenClaw can dispatch
+channel-backed `agent_end` hooks without waiting for them, and this adapter has
+no durable retry queue; process exit or network failure can lose a trace.
+This is observational telemetry, not a control or approval mechanism. Runtype
+cannot re-run telemetry-only agents without a callable external-agent endpoint.

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+//#region src/index.d.ts
+type HookEvent = Record<string, unknown>;
+type HookContext = Record<string, unknown>;
+type HookHandler = (event: HookEvent, context: HookContext) => void | Promise<void>;
+export interface OpenClawHookApi {
+  on(name: string, handler: HookHandler): void;
+  logger?: {
+    warn(message: string): void;
+  };
+}
+export interface OpenClawAdapterConfig {
+  agentId: string;
+  apiKey: string;
+  otlpUrl: string;
+  captureContent?: boolean;
+  onDiagnostic?: (code: string) => void;
+}
+export declare function createRuntypeOpenClawPlugin(config: OpenClawAdapterConfig): {
+  id: string;
+  name: string;
+  description: string;
+  register(api: OpenClawHookApi): void;
+};
+declare const environmentPlugin: {
+  id: string;
+  name: string;
+  description: string;
+  register(api: OpenClawHookApi): void;
+};
+//#endregion
+export { environmentPlugin as default };
+export {}

package/dist/index.mjs

@@ -0,0 +1,327 @@
+import { createHash } from "node:crypto";
+//#region package.json
+var version = "0.1.0";
+//#endregion
+//#region src/index.ts
+const MAX_CONTENT_BYTES = 32768;
+const ADAPTER_VERSION = version;
+function string(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function nativeId(event, context) {
+	return string(event.runId) ?? string(context.runId);
+}
+function id(value, bytes) {
+	return createHash("sha256").update(value).digest("hex").slice(0, bytes * 2);
+}
+function nanos(milliseconds) {
+	return (BigInt(Math.trunc(milliseconds)) * 1000000n).toString();
+}
+function number(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+function otlpAttributes(values) {
+	return Object.entries(values).map(([key, value]) => ({
+		key,
+		value: typeof value === "string" ? { stringValue: value } : typeof value === "boolean" ? { boolValue: value } : Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value }
+	}));
+}
+function configuredSecrets(apiKey) {
+	const secrets = Object.entries(process.env).filter(([name, value]) => /(?:API_KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)/i.test(name) && value && value.length >= 8).map(([, value]) => value);
+	secrets.push(apiKey);
+	return [...new Set(secrets)].sort((a, b) => b.length - a.length);
+}
+function capture(value, secrets, enabled) {
+	if (!enabled || value === void 0 || value === null) return void 0;
+	let serialized;
+	try {
+		serialized = JSON.stringify(value);
+	} catch {
+		return;
+	}
+	for (const secret of secrets) serialized = serialized.replaceAll(JSON.stringify(secret).slice(1, -1), "[REDACTED]");
+	return Buffer.byteLength(serialized, "utf8") <= MAX_CONTENT_BYTES ? serialized : void 0;
+}
+function message(role, value, secrets, enabled) {
+	return typeof value === "string" && value.length > 0 ? capture([{
+		role,
+		content: value
+	}], secrets, enabled) : void 0;
+}
+function assistantFailed(assistant) {
+	if (!assistant || typeof assistant !== "object") return false;
+	const final = assistant;
+	return final.stopReason === "error" || final.isError === true;
+}
+function finalAssistantFailed(messages) {
+	if (!Array.isArray(messages)) return false;
+	return assistantFailed([...messages].reverse().find((item) => item && typeof item === "object" && item.role === "assistant"));
+}
+function makeSpan(nativeRunId, operation, name, start, end, attributes, statusCode) {
+	return {
+		traceId: id(`openclaw:${nativeRunId}`, 16),
+		spanId: id(`openclaw:${nativeRunId}:${operation}`, 8),
+		parentSpanId: id(`openclaw:${nativeRunId}:root`, 8),
+		name,
+		startTimeUnixNano: nanos(start),
+		endTimeUnixNano: nanos(Math.max(start, end)),
+		attributes,
+		status: { code: statusCode }
+	};
+}
+function encode(spans, agentId) {
+	return JSON.stringify({ resourceSpans: [{
+		resource: { attributes: otlpAttributes({
+			"runtype.agent.id": agentId,
+			"runtype.adapter.name": "@runtypelabs/openclaw-adapter",
+			"runtype.adapter.version": ADAPTER_VERSION
+		}) },
+		scopeSpans: [{
+			scope: {
+				name: "@runtypelabs/openclaw-adapter",
+				version: ADAPTER_VERSION
+			},
+			spans: spans.map((span) => ({
+				traceId: span.traceId,
+				spanId: span.spanId,
+				...span.parentSpanId ? { parentSpanId: span.parentSpanId } : {},
+				name: span.name,
+				startTimeUnixNano: span.startTimeUnixNano,
+				endTimeUnixNano: span.endTimeUnixNano,
+				attributes: otlpAttributes(span.attributes),
+				status: span.status
+			}))
+		}]
+	}] });
+}
+function createRuntypeOpenClawPlugin(config) {
+	const active = /* @__PURE__ */ new Map();
+	const completed = /* @__PURE__ */ new Set();
+	const finishing = /* @__PURE__ */ new Set();
+	const secrets = configuredSecrets(config.apiKey);
+	const content = config.captureContent === true;
+	function run(nativeRunId) {
+		let current = active.get(nativeRunId);
+		if (current) return current;
+		if (active.size >= 1024) active.delete(active.keys().next().value);
+		current = {
+			startedAt: Date.now(),
+			inputs: [],
+			tools: /* @__PURE__ */ new Map(),
+			spans: [],
+			modelRefs: /* @__PURE__ */ new Set(),
+			inputTokens: 0,
+			outputTokens: 0,
+			measuredModels: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			cacheReadModels: 0,
+			cacheWriteModels: 0
+		};
+		active.set(nativeRunId, current);
+		return current;
+	}
+	function diagnostic(code) {
+		try {
+			config.onDiagnostic?.(code);
+		} catch {}
+	}
+	function settlePending(current) {
+		if (current.inputs.length === 0 && current.tools.size === 0) current.onSettled?.();
+	}
+	async function deliver(payload) {
+		try {
+			if (!(await fetch(config.otlpUrl, {
+				method: "POST",
+				redirect: "manual",
+				signal: AbortSignal.timeout(1e4),
+				headers: {
+					authorization: `Bearer ${config.apiKey}`,
+					"content-type": "application/json",
+					"x-runtype-agent-id": config.agentId
+				},
+				body: payload
+			})).ok) diagnostic("delivery_failed");
+		} catch {
+			diagnostic("delivery_failed");
+		}
+	}
+	return {
+		id: "runtype",
+		name: "Runtype Telemetry",
+		description: "Exports OpenClaw agent turns to Runtype",
+		register(api) {
+			api.on("llm_input", (event, context) => {
+				const key = nativeId(event, context);
+				if (!key || completed.has(key) || finishing.has(key)) return;
+				run(key).inputs.push({
+					at: Date.now(),
+					event
+				});
+			});
+			api.on("model_call_started", (event, context) => {
+				const key = nativeId(event, context);
+				const provider = string(event.provider);
+				const model = string(event.model);
+				if (!key || !provider || !model || completed.has(key)) return;
+				run(key).modelRefs.add(`${provider}/${model}`);
+			});
+			api.on("llm_output", (event, context) => {
+				const key = nativeId(event, context);
+				if (!key || completed.has(key)) return;
+				const current = run(key);
+				const input = current.inputs.shift();
+				const provider = string(event.provider) ?? string(input?.event.provider) ?? "unknown";
+				const model = string(event.model) ?? string(input?.event.model) ?? "unknown";
+				const texts = Array.isArray(event.assistantTexts) ? event.assistantTexts.filter((item) => typeof item === "string") : [];
+				const inputMessages = message("user", input?.event.prompt, secrets, content);
+				const outputMessages = message("assistant", texts.join("\n"), secrets, content);
+				const system = capture(input?.event.systemPrompt, secrets, content);
+				const usage = event.usage && typeof event.usage === "object" ? event.usage : {};
+				const inputTokens = number(usage.input);
+				const outputTokens = number(usage.output);
+				const cacheReadTokens = number(usage.cacheRead);
+				const cacheWriteTokens = number(usage.cacheWrite);
+				const inclusiveInputTokens = inputTokens === void 0 && cacheReadTokens === void 0 && cacheWriteTokens === void 0 ? void 0 : (inputTokens ?? 0) + (cacheReadTokens ?? 0) + (cacheWriteTokens ?? 0);
+				const index = current.spans.filter((span) => span.attributes["gen_ai.operation.name"] === "chat").length;
+				current.spans.push(makeSpan(key, `chat:${index}`, `chat ${model}`, input?.at ?? Date.now(), Date.now(), {
+					"gen_ai.operation.name": "chat",
+					"gen_ai.provider.name": provider,
+					"gen_ai.request.model": model,
+					"runtype.iteration": index,
+					...inclusiveInputTokens === void 0 ? {} : { "gen_ai.usage.input_tokens": inclusiveInputTokens },
+					...outputTokens === void 0 ? {} : { "gen_ai.usage.output_tokens": outputTokens },
+					...cacheReadTokens === void 0 ? {} : { "gen_ai.usage.cache_read.input_tokens": cacheReadTokens },
+					...cacheWriteTokens === void 0 ? {} : { "gen_ai.usage.cache_creation.input_tokens": cacheWriteTokens },
+					...inputMessages === void 0 ? {} : { "gen_ai.input.messages": inputMessages },
+					...outputMessages === void 0 ? {} : { "gen_ai.output.messages": outputMessages },
+					...system === void 0 ? {} : { "gen_ai.system_instructions": system }
+				}, assistantFailed(event.lastAssistant) ? 2 : 1));
+				current.firstInput ??= inputMessages;
+				current.lastOutput = outputMessages;
+				current.lastModel = model;
+				current.lastProvider = provider;
+				if (inclusiveInputTokens !== void 0 && outputTokens !== void 0) {
+					current.inputTokens += inclusiveInputTokens;
+					current.outputTokens += outputTokens;
+					current.measuredModels += 1;
+				}
+				if (cacheReadTokens !== void 0) {
+					current.cacheReadTokens += cacheReadTokens;
+					current.cacheReadModels += 1;
+				}
+				if (cacheWriteTokens !== void 0) {
+					current.cacheWriteTokens += cacheWriteTokens;
+					current.cacheWriteModels += 1;
+				}
+				settlePending(current);
+			});
+			api.on("before_tool_call", (event, context) => {
+				const key = nativeId(event, context);
+				const toolKey = string(event.toolCallId) ?? string(event.toolName);
+				if (!key || !toolKey || completed.has(key) || finishing.has(key)) return;
+				run(key).tools.set(toolKey, {
+					at: Date.now(),
+					event
+				});
+			});
+			api.on("after_tool_call", (event, context) => {
+				const key = nativeId(event, context);
+				if (!key || completed.has(key)) return;
+				const current = run(key);
+				const toolKey = string(event.toolCallId) ?? string(event.toolName);
+				const before = toolKey ? current.tools.get(toolKey) : void 0;
+				if (toolKey) current.tools.delete(toolKey);
+				const name = string(event.toolName) ?? string(before?.event.toolName) ?? "unknown";
+				const callId = string(event.toolCallId) ?? string(before?.event.toolCallId);
+				const args = capture(event.params, secrets, content);
+				const result = capture(event.result, secrets, content);
+				const index = current.spans.filter((span) => span.attributes["gen_ai.operation.name"] === "execute_tool").length + 1;
+				const now = Date.now();
+				current.spans.push(makeSpan(key, `tool:${index}`, `execute_tool ${name}`, before?.at ?? Math.max(1, now - (number(event.durationMs) ?? 0)), now, {
+					"gen_ai.operation.name": "execute_tool",
+					"gen_ai.tool.name": name,
+					...callId === void 0 ? {} : { "gen_ai.tool.call.id": callId },
+					...args === void 0 ? {} : { "gen_ai.tool.call.arguments": args },
+					...result === void 0 ? {} : { "gen_ai.tool.call.result": result }
+				}, string(event.error) === void 0 ? 1 : 2));
+				settlePending(current);
+			});
+			api.on("agent_end", async (event, context) => {
+				const key = nativeId(event, context);
+				if (!key || completed.has(key) || finishing.has(key)) return;
+				finishing.add(key);
+				const current = run(key);
+				const terminalAt = Date.now();
+				if (current.inputs.length > 0 || current.tools.size > 0) await new Promise((resolve) => {
+					const timer = setTimeout(() => {
+						current.onSettled = void 0;
+						resolve();
+					}, 1e3);
+					current.onSettled = () => {
+						clearTimeout(timer);
+						current.onSettled = void 0;
+						resolve();
+					};
+				});
+				active.delete(key);
+				completed.add(key);
+				finishing.delete(key);
+				if (completed.size > 2048) completed.delete(completed.values().next().value);
+				const chatSpans = current.spans.filter((span) => span.attributes["gen_ai.operation.name"] === "chat");
+				const usageComplete = current.measuredModels === chatSpans.length && current.modelRefs.size <= 1;
+				if (!usageComplete) for (const span of chatSpans) {
+					delete span.attributes["gen_ai.usage.input_tokens"];
+					delete span.attributes["gen_ai.usage.output_tokens"];
+					delete span.attributes["gen_ai.usage.cache_read.input_tokens"];
+					delete span.attributes["gen_ai.usage.cache_creation.input_tokens"];
+				}
+				const now = Math.max(terminalAt, ...current.spans.map((span) => Number(BigInt(span.endTimeUnixNano) / 1000000n)));
+				const duration = number(event.durationMs);
+				const startedAt = duration === void 0 ? current.startedAt : Math.min(current.startedAt, Math.max(1, terminalAt - duration));
+				const success = event.success === true && !finalAssistantFailed(event.messages);
+				const finalChat = chatSpans.at(-1);
+				if (!success && finalChat?.status?.code === 1 && finalChat.attributes["gen_ai.output.messages"] === void 0 && finalChat.attributes["gen_ai.usage.input_tokens"] === void 0 && finalChat.attributes["gen_ai.usage.output_tokens"] === void 0) finalChat.status = { code: 2 };
+				const root = makeSpan(key, "root", "invoke_agent", startedAt, now, {
+					"gen_ai.operation.name": "invoke_agent",
+					"runtype.stop_reason": success ? "stop" : "error",
+					...current.firstInput === void 0 ? {} : { "gen_ai.input.messages": current.firstInput },
+					...current.lastOutput === void 0 ? {} : { "gen_ai.output.messages": current.lastOutput },
+					...current.lastModel === void 0 ? {} : { "gen_ai.request.model": current.lastModel },
+					...current.lastProvider === void 0 ? {} : { "gen_ai.provider.name": current.lastProvider },
+					...current.measuredModels === 0 || !usageComplete ? {} : {
+						"gen_ai.usage.input_tokens": current.inputTokens,
+						"gen_ai.usage.output_tokens": current.outputTokens,
+						...current.cacheReadModels === chatSpans.length ? { "gen_ai.usage.cache_read.input_tokens": current.cacheReadTokens } : {},
+						...current.cacheWriteModels === chatSpans.length ? { "gen_ai.usage.cache_creation.input_tokens": current.cacheWriteTokens } : {}
+					}
+				}, success ? 1 : 2);
+				delete root.parentSpanId;
+				await deliver(encode([...current.spans, root], config.agentId));
+			});
+		}
+	};
+}
+const environmentPlugin = {
+	id: "runtype",
+	name: "Runtype Telemetry",
+	description: "Exports OpenClaw agent turns to Runtype",
+	register(api) {
+		const apiKey = process.env.RUNTYPE_API_KEY;
+		const agentId = process.env.RUNTYPE_AGENT_ID;
+		if (!apiKey || !agentId) {
+			api.logger?.warn("Runtype telemetry disabled: RUNTYPE_API_KEY and RUNTYPE_AGENT_ID are required");
+			return;
+		}
+		createRuntypeOpenClawPlugin({
+			apiKey,
+			agentId,
+			otlpUrl: process.env.RUNTYPE_OTLP_URL ?? "https://api.runtype.com/v1/otel/v1/traces",
+			captureContent: process.env.RUNTYPE_CAPTURE_CONTENT === "true",
+			onDiagnostic: (code) => api.logger?.warn(`Runtype telemetry ${code}`)
+		}).register(api);
+	}
+};
+//#endregion
+export { createRuntypeOpenClawPlugin, environmentPlugin as default };
+

package/openclaw.plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "runtype",
+  "name": "Runtype Telemetry",
+  "description": "Export OpenClaw agent turns to Runtype",
+  "activation": { "onStartup": true },
+  "configSchema": { "type": "object", "additionalProperties": false }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@runtypelabs/openclaw-adapter",
+  "version": "0.1.0",
+  "description": "OpenClaw run telemetry for Runtype",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.mjs"
+    ]
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "tsdown": "^0.23.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runtypelabs/core",
+    "directory": "packages/openclaw-adapter"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.tests.json",
+    "lint": "eslint . --max-warnings 0"
+  }
+}