@contextcompany/openclaw 1.0.0

package/README.md

@@ -0,0 +1,86 @@
+# @contextcompany/openclaw
+
+The Context Company observability plugin for [OpenClaw](https://openclaw.ai).
+
+Captures LLM calls, tool executions, and agent lifecycle events from OpenClaw's plugin hook system, then exports them to The Context Company for visualization and analysis.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+openclaw plugins install @contextcompany/openclaw
+```
+
+### 2. Configure
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "allow": ["@contextcompany/openclaw"],
+    "entries": {
+      "@contextcompany/openclaw": {
+        "enabled": true,
+        "config": {
+          "apiKey": "${TCC_API_KEY}"
+        }
+      }
+    }
+  }
+}
+```
+
+### 3. Restart
+
+```bash
+openclaw gateway restart
+```
+
+That's it. The plugin hooks into the agent runtime and starts sending traces to TCC.
+
+## Alternative: Manual Registration
+
+If you prefer to register from a custom extension:
+
+```ts
+// extensions/tcc-observability/index.ts
+import { register } from "@contextcompany/openclaw";
+
+export default async function (api) {
+  register(api);
+}
+```
+
+With explicit config:
+
+```ts
+register(api, {
+  apiKey: "tcc_...",
+  endpoint: "https://api.thecontext.company/v1/openclaw",
+  debug: true,
+});
+```
+
+## Configuration
+
+| Option | Env Var | Default | Description |
+|--------|---------|---------|-------------|
+| `apiKey` | `TCC_API_KEY` | — | Your Context Company API key |
+| `endpoint` | `TCC_URL` | Auto-detected from key | Ingestion endpoint URL |
+| `debug` | `TCC_DEBUG` | `false` | Enable debug logging |
+
+## How It Works
+
+The plugin hooks into OpenClaw's agent lifecycle events:
+
+| Hook | What it captures |
+|------|-----------------|
+| `llm_input` | LLM call start — model, prompt, system prompt, history |
+| `llm_output` | LLM call end — response, token usage, cost |
+| `before_tool_call` | Tool execution start — tool name, arguments |
+| `after_tool_call` | Tool execution end — result, errors, duration |
+| `agent_end` | Run complete — success/failure, full message history |
+
+All events are collected during the agent run and sent as a single batch when the run completes. Sessions that never receive an `agent_end` are flushed after 30 minutes.

package/dist/index.cjs

@@ -0,0 +1,151 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// src/transport.ts
+var MAX_RETRIES = 2;
+var INITIAL_BACKOFF_MS = 1e3;
+async function sendToTcc(payload, apiKey, url, debug, log) {
+  const body = JSON.stringify(payload);
+  if (debug) log.info(`sending ${body.length} bytes to ${url}`);
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    if (attempt > 0)
+      await new Promise((r) => setTimeout(r, INITIAL_BACKOFF_MS * 2 ** (attempt - 1)));
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`
+        },
+        body
+      });
+      if (res.ok) {
+        if (debug) log.info("sent ok");
+        return;
+      }
+      const text = await res.text();
+      if (res.status !== 429 && res.status < 500) {
+        log.warn(`ingestion failed (${res.status}): ${text}`);
+        return;
+      }
+    } catch (err) {
+      if (attempt === MAX_RETRIES)
+        log.warn(`ingestion failed after ${MAX_RETRIES + 1} attempts: ${err}`);
+    }
+  }
+  log.warn(`ingestion failed after ${MAX_RETRIES + 1} attempts (server errors)`);
+}
+function safeClone(obj) {
+  try {
+    return JSON.parse(JSON.stringify(obj));
+  } catch {
+    return String(obj);
+  }
+}
+
+// src/plugin.ts
+function registerHooks(api, configOverrides) {
+  const activeSessions = /* @__PURE__ */ new Map();
+  const pluginConfig = {
+    ...api.pluginConfig ?? {},
+    ...configOverrides
+  };
+  const debug = pluginConfig.debug === true || process.env.TCC_DEBUG === "true";
+  const log = {
+    info: (msg) => console.log(`[tcc] ${msg}`),
+    warn: (msg) => console.warn(`[tcc] ${msg}`)
+  };
+  const apiKey = (typeof pluginConfig.apiKey === "string" ? pluginConfig.apiKey : null) ?? process.env.TCC_API_KEY;
+  if (!apiKey) {
+    log.warn("No TCC_API_KEY found. Set env var or plugin config. Disabled.");
+    return;
+  }
+  const url = (typeof pluginConfig.endpoint === "string" ? pluginConfig.endpoint : null) ?? process.env.TCC_URL ?? (apiKey.startsWith("dev_") ? "https://dev.thecontext.company/v1/openclaw" : "https://api.thecontext.company/v1/openclaw");
+  log.info(`exporting runs to ${url}`);
+  const STALE_SESSION_MS = 30 * 60 * 1e3;
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, session] of activeSessions) {
+      if (now - session.startedAt > STALE_SESSION_MS) {
+        if (debug) log.info(`flushing stale session: ${key}`);
+        sendToTcc(
+          { framework: "openclaw", events: session.events, stale: true },
+          apiKey,
+          url,
+          debug,
+          log
+        ).catch((err) => {
+          log.warn(`failed to send stale session: ${err}`);
+        });
+        activeSessions.delete(key);
+      }
+    }
+  }, 5 * 60 * 1e3);
+  if (cleanupInterval.unref) cleanupInterval.unref();
+  function pushEvent(hook, event, ctx) {
+    const sessionKey = ctx?.sessionKey;
+    if (!sessionKey) return;
+    let session = activeSessions.get(sessionKey);
+    if (!session) {
+      session = { events: [], startedAt: Date.now() };
+      activeSessions.set(sessionKey, session);
+    }
+    session.events.push({
+      hook,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      event: safeClone(event),
+      context: safeClone(ctx)
+    });
+  }
+  api.on("llm_input", (event, ctx) => {
+    pushEvent("llm_input", event, ctx);
+    if (debug) log.info(`llm_input (model: ${event.model})`);
+  });
+  api.on("llm_output", (event, ctx) => {
+    pushEvent("llm_output", event, ctx);
+    if (debug) log.info(`llm_output (model: ${event.model})`);
+  });
+  api.on("before_tool_call", (event, ctx) => {
+    pushEvent("before_tool_call", event, ctx);
+    if (debug) log.info(`before_tool_call (tool: ${event.toolName})`);
+  });
+  api.on("after_tool_call", (event, ctx) => {
+    pushEvent("after_tool_call", event, ctx);
+    if (debug) log.info(`after_tool_call (tool: ${event.toolName})`);
+  });
+  api.on("agent_end", (event, ctx) => {
+    const sessionKey = ctx?.sessionKey;
+    if (!sessionKey) return;
+    pushEvent("agent_end", event, ctx);
+    queueMicrotask(() => {
+      const session = activeSessions.get(sessionKey);
+      if (!session) return;
+      if (debug)
+        log.info(`agent_end \u2014 sending ${session.events.length} events`);
+      const payload = {
+        framework: "openclaw",
+        events: session.events
+      };
+      sendToTcc(payload, apiKey, url, debug, log).catch((err) => {
+        log.warn(`failed to send events: ${err}`);
+      });
+      activeSessions.delete(sessionKey);
+    });
+  });
+}
+var plugin = {
+  id: "@contextcompany/openclaw",
+  name: "The Context Company",
+  description: "Agent observability \u2014 captures LLM calls, tool executions, and agent lifecycle events",
+  register(api) {
+    registerHooks(api);
+  }
+};
+var plugin_default = plugin;
+function register(api, configOverrides) {
+  registerHooks(api, configOverrides);
+}
+
+exports.default = plugin_default;
+exports.register = register;

package/dist/index.d.cts

@@ -0,0 +1,61 @@
+/** Configuration for the TCC OpenClaw plugin. */
+type OpenClawPluginConfig = {
+    /** TCC API key. Falls back to TCC_API_KEY env var. */
+    apiKey?: string;
+    /** TCC ingestion endpoint. Falls back to TCC_URL env var, then auto-detected from key prefix. */
+    endpoint?: string;
+    /** Enable debug logging. Falls back to TCC_DEBUG env var. */
+    debug?: boolean;
+};
+
+/**
+ * @contextcompany/openclaw — OpenClaw plugin for The Context Company
+ *
+ * Thin forwarder: collects raw hook events during an agent run,
+ * then sends them all as one batch on agent_end.
+ *
+ * All parsing/transformation happens server-side.
+ */
+
+/**
+ * Full OpenClaw plugin object — install via `openclaw plugins install`
+ * and configure in `openclaw.json` under `plugins.entries`.
+ *
+ * @example
+ * ```json
+ * {
+ *   "plugins": {
+ *     "allow": ["@contextcompany/openclaw"],
+ *     "entries": {
+ *       "@contextcompany/openclaw": {
+ *         "enabled": true,
+ *         "config": {
+ *           "apiKey": "${TCC_API_KEY}"
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    register(api: any): void;
+};
+
+/**
+ * Named export for manual registration (e.g. from a custom extension).
+ *
+ * @example
+ * ```ts
+ * import { register } from "@contextcompany/openclaw";
+ * export default async function (api) {
+ *   register(api, { apiKey: "tcc_...", debug: true });
+ * }
+ * ```
+ */
+declare function register(api: any, configOverrides?: OpenClawPluginConfig): void;
+
+export { type OpenClawPluginConfig, plugin as default, register };

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+/** Configuration for the TCC OpenClaw plugin. */
+type OpenClawPluginConfig = {
+    /** TCC API key. Falls back to TCC_API_KEY env var. */
+    apiKey?: string;
+    /** TCC ingestion endpoint. Falls back to TCC_URL env var, then auto-detected from key prefix. */
+    endpoint?: string;
+    /** Enable debug logging. Falls back to TCC_DEBUG env var. */
+    debug?: boolean;
+};
+
+/**
+ * @contextcompany/openclaw — OpenClaw plugin for The Context Company
+ *
+ * Thin forwarder: collects raw hook events during an agent run,
+ * then sends them all as one batch on agent_end.
+ *
+ * All parsing/transformation happens server-side.
+ */
+
+/**
+ * Full OpenClaw plugin object — install via `openclaw plugins install`
+ * and configure in `openclaw.json` under `plugins.entries`.
+ *
+ * @example
+ * ```json
+ * {
+ *   "plugins": {
+ *     "allow": ["@contextcompany/openclaw"],
+ *     "entries": {
+ *       "@contextcompany/openclaw": {
+ *         "enabled": true,
+ *         "config": {
+ *           "apiKey": "${TCC_API_KEY}"
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    register(api: any): void;
+};
+
+/**
+ * Named export for manual registration (e.g. from a custom extension).
+ *
+ * @example
+ * ```ts
+ * import { register } from "@contextcompany/openclaw";
+ * export default async function (api) {
+ *   register(api, { apiKey: "tcc_...", debug: true });
+ * }
+ * ```
+ */
+declare function register(api: any, configOverrides?: OpenClawPluginConfig): void;
+
+export { type OpenClawPluginConfig, plugin as default, register };

package/dist/index.js

@@ -0,0 +1,146 @@
+// src/transport.ts
+var MAX_RETRIES = 2;
+var INITIAL_BACKOFF_MS = 1e3;
+async function sendToTcc(payload, apiKey, url, debug, log) {
+  const body = JSON.stringify(payload);
+  if (debug) log.info(`sending ${body.length} bytes to ${url}`);
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    if (attempt > 0)
+      await new Promise((r) => setTimeout(r, INITIAL_BACKOFF_MS * 2 ** (attempt - 1)));
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`
+        },
+        body
+      });
+      if (res.ok) {
+        if (debug) log.info("sent ok");
+        return;
+      }
+      const text = await res.text();
+      if (res.status !== 429 && res.status < 500) {
+        log.warn(`ingestion failed (${res.status}): ${text}`);
+        return;
+      }
+    } catch (err) {
+      if (attempt === MAX_RETRIES)
+        log.warn(`ingestion failed after ${MAX_RETRIES + 1} attempts: ${err}`);
+    }
+  }
+  log.warn(`ingestion failed after ${MAX_RETRIES + 1} attempts (server errors)`);
+}
+function safeClone(obj) {
+  try {
+    return JSON.parse(JSON.stringify(obj));
+  } catch {
+    return String(obj);
+  }
+}
+
+// src/plugin.ts
+function registerHooks(api, configOverrides) {
+  const activeSessions = /* @__PURE__ */ new Map();
+  const pluginConfig = {
+    ...api.pluginConfig ?? {},
+    ...configOverrides
+  };
+  const debug = pluginConfig.debug === true || process.env.TCC_DEBUG === "true";
+  const log = {
+    info: (msg) => console.log(`[tcc] ${msg}`),
+    warn: (msg) => console.warn(`[tcc] ${msg}`)
+  };
+  const apiKey = (typeof pluginConfig.apiKey === "string" ? pluginConfig.apiKey : null) ?? process.env.TCC_API_KEY;
+  if (!apiKey) {
+    log.warn("No TCC_API_KEY found. Set env var or plugin config. Disabled.");
+    return;
+  }
+  const url = (typeof pluginConfig.endpoint === "string" ? pluginConfig.endpoint : null) ?? process.env.TCC_URL ?? (apiKey.startsWith("dev_") ? "https://dev.thecontext.company/v1/openclaw" : "https://api.thecontext.company/v1/openclaw");
+  log.info(`exporting runs to ${url}`);
+  const STALE_SESSION_MS = 30 * 60 * 1e3;
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, session] of activeSessions) {
+      if (now - session.startedAt > STALE_SESSION_MS) {
+        if (debug) log.info(`flushing stale session: ${key}`);
+        sendToTcc(
+          { framework: "openclaw", events: session.events, stale: true },
+          apiKey,
+          url,
+          debug,
+          log
+        ).catch((err) => {
+          log.warn(`failed to send stale session: ${err}`);
+        });
+        activeSessions.delete(key);
+      }
+    }
+  }, 5 * 60 * 1e3);
+  if (cleanupInterval.unref) cleanupInterval.unref();
+  function pushEvent(hook, event, ctx) {
+    const sessionKey = ctx?.sessionKey;
+    if (!sessionKey) return;
+    let session = activeSessions.get(sessionKey);
+    if (!session) {
+      session = { events: [], startedAt: Date.now() };
+      activeSessions.set(sessionKey, session);
+    }
+    session.events.push({
+      hook,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      event: safeClone(event),
+      context: safeClone(ctx)
+    });
+  }
+  api.on("llm_input", (event, ctx) => {
+    pushEvent("llm_input", event, ctx);
+    if (debug) log.info(`llm_input (model: ${event.model})`);
+  });
+  api.on("llm_output", (event, ctx) => {
+    pushEvent("llm_output", event, ctx);
+    if (debug) log.info(`llm_output (model: ${event.model})`);
+  });
+  api.on("before_tool_call", (event, ctx) => {
+    pushEvent("before_tool_call", event, ctx);
+    if (debug) log.info(`before_tool_call (tool: ${event.toolName})`);
+  });
+  api.on("after_tool_call", (event, ctx) => {
+    pushEvent("after_tool_call", event, ctx);
+    if (debug) log.info(`after_tool_call (tool: ${event.toolName})`);
+  });
+  api.on("agent_end", (event, ctx) => {
+    const sessionKey = ctx?.sessionKey;
+    if (!sessionKey) return;
+    pushEvent("agent_end", event, ctx);
+    queueMicrotask(() => {
+      const session = activeSessions.get(sessionKey);
+      if (!session) return;
+      if (debug)
+        log.info(`agent_end \u2014 sending ${session.events.length} events`);
+      const payload = {
+        framework: "openclaw",
+        events: session.events
+      };
+      sendToTcc(payload, apiKey, url, debug, log).catch((err) => {
+        log.warn(`failed to send events: ${err}`);
+      });
+      activeSessions.delete(sessionKey);
+    });
+  });
+}
+var plugin = {
+  id: "@contextcompany/openclaw",
+  name: "The Context Company",
+  description: "Agent observability \u2014 captures LLM calls, tool executions, and agent lifecycle events",
+  register(api) {
+    registerHooks(api);
+  }
+};
+var plugin_default = plugin;
+function register(api, configOverrides) {
+  registerHooks(api, configOverrides);
+}
+
+export { plugin_default as default, register };

package/openclaw.plugin.json

@@ -0,0 +1,36 @@
+{
+  "id": "@contextcompany/openclaw",
+  "name": "The Context Company",
+  "description": "Agent observability — captures LLM calls, tool executions, and agent lifecycle events",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": { "type": "boolean" },
+      "apiKey": { "type": "string" },
+      "endpoint": { "type": "string" },
+      "debug": { "type": "boolean" }
+    }
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "Tracing Enabled",
+      "help": "Enable trace export to The Context Company."
+    },
+    "apiKey": {
+      "label": "TCC API Key",
+      "placeholder": "tcc_...",
+      "sensitive": true,
+      "help": "Falls back to TCC_API_KEY environment variable."
+    },
+    "endpoint": {
+      "label": "TCC Endpoint URL",
+      "placeholder": "https://api.thecontext.company/v1/openclaw",
+      "help": "Auto-detected from API key prefix. Override for custom deployments."
+    },
+    "debug": {
+      "label": "Debug Logging",
+      "help": "Log hook events and transport details to console."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@contextcompany/openclaw",
+  "version": "1.0.0",
+  "description": "The Context Company integration for OpenClaw",
+  "type": "module",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "src",
+    "README.md"
+  ],
+  "openclaw": {
+    "extension": "src/index.ts"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "pnpm build --watch"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "openclaw",
+    "observability",
+    "tracing",
+    "monitoring",
+    "context-company",
+    "ai-agents"
+  ],
+  "homepage": "https://github.com/The-Context-Company/observatory/tree/main/packages/ts/openclaw#readme",
+  "bugs": {
+    "url": "https://github.com/The-Context-Company/observatory/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/The-Context-Company/observatory",
+    "directory": "packages/ts/openclaw"
+  },
+  "author": "The Context Company",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default, register, type OpenClawPluginConfig } from "./plugin.js";

package/src/plugin.ts

@@ -0,0 +1,202 @@
+/**
+ * @contextcompany/openclaw — OpenClaw plugin for The Context Company
+ *
+ * Thin forwarder: collects raw hook events during an agent run,
+ * then sends them all as one batch on agent_end.
+ *
+ * All parsing/transformation happens server-side.
+ */
+
+import type { ActiveSession, OpenClawPluginConfig } from "./types.js";
+export type { OpenClawPluginConfig } from "./types.js";
+import { safeClone, sendToTcc } from "./transport.js";
+
+function registerHooks(
+  api: any,
+  configOverrides?: OpenClawPluginConfig,
+): void {
+  const activeSessions = new Map<string, ActiveSession>();
+
+  const pluginConfig: Record<string, unknown> = {
+    ...(api.pluginConfig ?? {}),
+    ...configOverrides,
+  };
+  const debug =
+    pluginConfig.debug === true || process.env.TCC_DEBUG === "true";
+
+  const log = {
+    info: (msg: string) => console.log(`[tcc] ${msg}`),
+    warn: (msg: string) => console.warn(`[tcc] ${msg}`),
+  };
+
+  const apiKey =
+    (typeof pluginConfig.apiKey === "string" ? pluginConfig.apiKey : null) ??
+    process.env.TCC_API_KEY;
+
+  if (!apiKey) {
+    log.warn("No TCC_API_KEY found. Set env var or plugin config. Disabled.");
+    return;
+  }
+
+  const url =
+    (typeof pluginConfig.endpoint === "string"
+      ? pluginConfig.endpoint
+      : null) ??
+    process.env.TCC_URL ??
+    (apiKey.startsWith("dev_")
+      ? "https://dev.thecontext.company/v1/openclaw"
+      : "https://api.thecontext.company/v1/openclaw");
+
+  log.info(`exporting runs to ${url}`);
+
+  // -------------------------------------------------------------------
+  // Stale session cleanup — flush sessions that never got an agent_end
+  // -------------------------------------------------------------------
+  const STALE_SESSION_MS = 30 * 60 * 1000; // 30 minutes
+
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, session] of activeSessions) {
+      if (now - session.startedAt > STALE_SESSION_MS) {
+        if (debug) log.info(`flushing stale session: ${key}`);
+
+        sendToTcc(
+          { framework: "openclaw", events: session.events, stale: true },
+          apiKey,
+          url,
+          debug,
+          log,
+        ).catch((err) => {
+          log.warn(`failed to send stale session: ${err}`);
+        });
+
+        activeSessions.delete(key);
+      }
+    }
+  }, 5 * 60 * 1000); // check every 5 minutes
+
+  if (cleanupInterval.unref) cleanupInterval.unref();
+
+  // -------------------------------------------------------------------
+  // Helper: push a raw event into the session's event list
+  // -------------------------------------------------------------------
+  function pushEvent(hook: string, event: unknown, ctx: unknown): void {
+    const sessionKey = (ctx as any)?.sessionKey;
+    if (!sessionKey) return;
+
+    let session = activeSessions.get(sessionKey);
+    if (!session) {
+      session = { events: [], startedAt: Date.now() };
+      activeSessions.set(sessionKey, session);
+    }
+
+    session.events.push({
+      hook,
+      timestamp: new Date().toISOString(),
+      event: safeClone(event) as Record<string, unknown>,
+      context: safeClone(ctx) as Record<string, unknown>,
+    });
+  }
+
+  // -------------------------------------------------------------------
+  // Hooks: collect raw events
+  // -------------------------------------------------------------------
+
+  api.on("llm_input", (event: any, ctx: any) => {
+    pushEvent("llm_input", event, ctx);
+    if (debug) log.info(`llm_input (model: ${event.model})`);
+  });
+
+  api.on("llm_output", (event: any, ctx: any) => {
+    pushEvent("llm_output", event, ctx);
+    if (debug) log.info(`llm_output (model: ${event.model})`);
+  });
+
+  api.on("before_tool_call", (event: any, ctx: any) => {
+    pushEvent("before_tool_call", event, ctx);
+    if (debug) log.info(`before_tool_call (tool: ${event.toolName})`);
+  });
+
+  api.on("after_tool_call", (event: any, ctx: any) => {
+    pushEvent("after_tool_call", event, ctx);
+    if (debug) log.info(`after_tool_call (tool: ${event.toolName})`);
+  });
+
+  api.on("agent_end", (event: any, ctx: any) => {
+    const sessionKey = ctx?.sessionKey;
+    if (!sessionKey) return;
+
+    pushEvent("agent_end", event, ctx);
+
+    // Defer sending to a microtask so llm_output (which fires on the
+    // same synchronous tick as agent_end) gets collected first.
+    queueMicrotask(() => {
+      const session = activeSessions.get(sessionKey);
+      if (!session) return;
+
+      if (debug)
+        log.info(`agent_end — sending ${session.events.length} events`);
+
+      const payload = {
+        framework: "openclaw",
+        events: session.events,
+      };
+
+      sendToTcc(payload, apiKey, url, debug, log).catch((err) => {
+        log.warn(`failed to send events: ${err}`);
+      });
+
+      activeSessions.delete(sessionKey);
+    });
+  });
+}
+
+/**
+ * Full OpenClaw plugin object — install via `openclaw plugins install`
+ * and configure in `openclaw.json` under `plugins.entries`.
+ *
+ * @example
+ * ```json
+ * {
+ *   "plugins": {
+ *     "allow": ["@contextcompany/openclaw"],
+ *     "entries": {
+ *       "@contextcompany/openclaw": {
+ *         "enabled": true,
+ *         "config": {
+ *           "apiKey": "${TCC_API_KEY}"
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+const plugin = {
+  id: "@contextcompany/openclaw",
+  name: "The Context Company",
+  description: "Agent observability — captures LLM calls, tool executions, and agent lifecycle events",
+  register(api: any) {
+    registerHooks(api);
+  },
+};
+
+export default plugin;
+
+/**
+ * Named export for manual registration (e.g. from a custom extension).
+ *
+ * @example
+ * ```ts
+ * import { register } from "@contextcompany/openclaw";
+ * export default async function (api) {
+ *   register(api, { apiKey: "tcc_...", debug: true });
+ * }
+ * ```
+ */
+export function register(
+  api: any,
+  configOverrides?: OpenClawPluginConfig,
+): void {
+  registerHooks(api, configOverrides);
+}

package/src/transport.ts

@@ -0,0 +1,49 @@
+const MAX_RETRIES = 2;
+const INITIAL_BACKOFF_MS = 1000;
+
+export async function sendToTcc(
+  payload: Record<string, unknown>,
+  apiKey: string,
+  url: string,
+  debug: boolean,
+  log: { info: (m: string) => void; warn: (m: string) => void },
+): Promise<void> {
+  const body = JSON.stringify(payload);
+  if (debug) log.info(`sending ${body.length} bytes to ${url}`);
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    if (attempt > 0)
+      await new Promise((r) => setTimeout(r, INITIAL_BACKOFF_MS * 2 ** (attempt - 1)));
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body,
+      });
+      if (res.ok) {
+        if (debug) log.info("sent ok");
+        return;
+      }
+      const text = await res.text();
+      if (res.status !== 429 && res.status < 500) {
+        log.warn(`ingestion failed (${res.status}): ${text}`);
+        return;
+      }
+    } catch (err) {
+      if (attempt === MAX_RETRIES)
+        log.warn(`ingestion failed after ${MAX_RETRIES + 1} attempts: ${err}`);
+    }
+  }
+  log.warn(`ingestion failed after ${MAX_RETRIES + 1} attempts (server errors)`);
+}
+
+export function safeClone(obj: unknown): unknown {
+  try {
+    return JSON.parse(JSON.stringify(obj));
+  } catch {
+    return String(obj);
+  }
+}

package/src/types.ts

@@ -0,0 +1,23 @@
+/** A single raw hook event captured from OpenClaw's plugin API. */
+export type RawEvent = {
+  hook: string;
+  timestamp: string;
+  event: Record<string, unknown>;
+  context: Record<string, unknown>;
+};
+
+/** In-flight session accumulating events before send. */
+export type ActiveSession = {
+  events: RawEvent[];
+  startedAt: number;
+};
+
+/** Configuration for the TCC OpenClaw plugin. */
+export type OpenClawPluginConfig = {
+  /** TCC API key. Falls back to TCC_API_KEY env var. */
+  apiKey?: string;
+  /** TCC ingestion endpoint. Falls back to TCC_URL env var, then auto-detected from key prefix. */
+  endpoint?: string;
+  /** Enable debug logging. Falls back to TCC_DEBUG env var. */
+  debug?: boolean;
+};