@agimon-ai/doompi-telemetry 0.0.1-alpha.21 → 0.0.1-alpha.22

package/README.md

@@ -1,14 +1,14 @@
 # @agimon-ai/doompi-telemetry
 
-**Measure the harness without recording the work.**
+Host-neutral telemetry helpers and Log Sink adapters shared by DoomPi packages.
 
-This is the shared telemetry library for Doompi runtimes. It emits metadata-only counters
-and spans: never prompt text, file contents, or the material the agent is working on. One
-library keeps event names and attributes consistent across extensions, which makes the
-result useful for debugging instead of merely plentiful.
+This is a library, not a Pi extension. It has no Pi manifest or Pi peer dependency and should not be added to a DoomPi layer.
 
-This is part of [Doompi](https://www.npmjs.com/package/@agimon-ai/doompi). It is usually a
-transitive dependency rather than something users install on its own.
+> **Alpha:** telemetry attributes and sink contracts may change between releases.
+
+## Requirements
+
+- Node.js 22.19.0 or newer
 
 ## Install
 
@@ -16,17 +16,45 @@ transitive dependency rather than something users install on its own.
 npm install @agimon-ai/doompi-telemetry
 ```
 
-## How it loads
+## Use
+
+```ts
+import { createDoomTelemetry } from '@agimon-ai/doompi-telemetry';
+
+const telemetry = createDoomTelemetry({
+  serviceName: 'review-extension',
+  packageName: '@example/review-extension',
+  cwd: process.cwd(),
+  env: process.env,
+  enableLogs: true,
+  enableTraces: true,
+});
+
+await telemetry.recordEvent('review.started', { 'review.file_count': 3 });
+await telemetry.flush();
+await telemetry.shutdown();
+```
+
+The root and `/telemetry` subpath expose `createDoomTelemetry`, attribute sanitization, header creation, record subscriptions, and related types.
 
-This is a library, not a Pi extension. Doompi packages import it directly; there is no
-extension entry and nothing to add to `.doom/modes.yaml`.
+## Data and failure behavior
 
-## Entry points
+The adapter sanitizes attribute shapes and hashes selected identifiers before export. It is designed for operational metadata, but callers remain responsible for the values they pass. Do not attach prompt text, file contents, credentials, or unreviewed user data.
 
-| Import                                  | Purpose            |
-| --------------------------------------- | ------------------ |
-| `@agimon-ai/doompi-telemetry`           | Shared library API |
-| `@agimon-ai/doompi-telemetry/telemetry` | Telemetry helpers  |
+Exception export is optional and can include error names, messages, and stack context. Those fields may disclose code paths or values even when ordinary attributes are metadata-only.
+
+When no endpoint is configured, telemetry export becomes a no-op rather than breaking the host. Explicit file fallback must be enabled by the caller; it is not silently selected. Sink initialization, record, flush, and shutdown behavior is surfaced through status/diagnostic callbacks.
+
+Common controls used by DoomPi hosts include `AGENT_TELEMETRY_DISABLED`, `OTEL_SDK_DISABLED`, and `AGENT_OTEL_TRACES`. Hosts must decide whether these variables, endpoint configuration, or explicit options have precedence in their integration.
+
+## Development
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agimon-ai/doompi-telemetry",
-  "version": "0.0.1-alpha.21",
+  "version": "0.0.1-alpha.22",
   "description": "Metadata-only LogSink telemetry for Doompi runtimes",
   "keywords": [
     "ai",
@@ -37,7 +37,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@agimon-ai/log-sink-mcp": "0.29.11"
+    "@agimon-ai/log-sink-mcp": "0.29.12"
   },
   "devDependencies": {
     "@types/node": "26.1.1",