@cybernetyx1/atlasflow-observability 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2026 Cybernetyx. All rights reserved.
+
+This software and its source code are the proprietary and confidential property
+of the copyright holder. The software is original work authored independently.
+
+No part of this software may be copied, reproduced, modified, published,
+distributed, sublicensed, or sold in any form or by any means without the prior
+written permission of the copyright holder, except as expressly permitted by a
+separate written agreement.
+
+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 COPYRIGHT
+HOLDER 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,36 @@
+# @cybernetyx1/atlasflow-observability
+
+Lightweight JSON logging and in-process metrics observers for the AtlasFlow runtime event stream.
+
+## Install
+
+```sh
+pnpm add @cybernetyx1/atlasflow-observability
+```
+
+Part of the AtlasFlow monorepo. Proprietary.
+
+## Usage
+
+Subscribe an observer to the runtime event bus with `observe()`. `createJsonLogObserver` turns events into JSONL-friendly log records (with filtering and tool-argument redaction); `createMetricsObserver` aggregates run/turn/tool/error counts and token cost, exposing `snapshot()` and `reset()`.
+
+```ts
+import { observe } from "@cybernetyx1/atlasflow-runtime";
+import { createJsonLogObserver, createMetricsObserver } from "@cybernetyx1/atlasflow-observability";
+
+observe(createJsonLogObserver());
+
+const metrics = createMetricsObserver();
+observe(metrics.observe);
+
+// later
+console.log(metrics.snapshot()); // { runsStarted, runsSucceeded, totalTokens, costTotal, byAgent, ... }
+```
+
+In generated servers these are wired automatically: set `ATLASFLOW_OBSERVABILITY=metrics` (or `all`), or `ATLASFLOW_METRICS=true`, to enable the metrics observer and surface it on the authenticated `/admin/metrics` route.
+
+Exports: `createJsonLogObserver`, `createMetricsObserver`, and the `LogLevel` / `JsonLogRecord` / `JsonLogObserverOptions` / `AgentMetrics` / `ObservabilityMetrics` / `MetricsObserver` types.
+
+## License
+
+Proprietary. © 2026 Cybernetyx. See LICENSE.

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import { AtlasEvent, EventSubscriber } from '@cybernetyx1/atlasflow-runtime';
+
+/**
+ * @cybernetyx1/atlasflow-observability — lightweight observers for AtlasFlow's event
+ * stream. Use this when you want structured logs and counters without wiring a
+ * full OpenTelemetry provider.
+ */
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface JsonLogRecord {
+    timestamp: string;
+    type: AtlasEvent["type"];
+    level: LogLevel;
+    runId?: string;
+    session?: string;
+    event: AtlasEvent;
+}
+interface JsonLogObserverOptions {
+    /** Called with one JSON-ready record per event. Defaults to console.log(JSON). */
+    sink?: (record: JsonLogRecord) => void | Promise<void>;
+    /** Keep only selected event types. */
+    include?: AtlasEvent["type"][];
+    /** Drop selected event types after include filtering. */
+    exclude?: AtlasEvent["type"][];
+    /** Include high-volume text/thinking deltas. Defaults to false unless include is set. */
+    includeDeltas?: boolean;
+    /** Replace tool-call arguments with a marker before logging. Defaults to true. */
+    redactToolArguments?: boolean;
+    /** Inspect/redact events before logging. Return undefined to drop. */
+    sanitize?: (event: AtlasEvent) => AtlasEvent | undefined;
+}
+interface AgentMetrics {
+    runsStarted: number;
+    runsSucceeded: number;
+    runsFailed: number;
+    runErrors: number;
+    toolCalls: number;
+    toolErrors: number;
+    totalTokens: number;
+    costTotal: number;
+}
+interface ObservabilityMetrics extends AgentMetrics {
+    runsEnded: number;
+    operationsStarted: number;
+    operationsEnded: number;
+    operationErrors: number;
+    taskCalls: number;
+    taskErrors: number;
+    ruleBlocks: number;
+    ruleWarnings: number;
+    compactedTokens: number;
+    byAgent: Record<string, AgentMetrics>;
+}
+interface MetricsObserver {
+    observe: EventSubscriber;
+    snapshot(): ObservabilityMetrics;
+    reset(): void;
+}
+/** Create a JSONL-friendly event observer with filtering and redaction hooks. */
+declare function createJsonLogObserver(options?: JsonLogObserverOptions): EventSubscriber;
+/**
+ * Create an in-process metrics observer. The returned observer is synchronous
+ * and intentionally tiny; export `snapshot()` to your own metrics backend.
+ */
+declare function createMetricsObserver(): MetricsObserver;
+
+export { type AgentMetrics, type JsonLogObserverOptions, type JsonLogRecord, type LogLevel, type MetricsObserver, type ObservabilityMetrics, createJsonLogObserver, createMetricsObserver };

package/dist/index.js

@@ -0,0 +1,176 @@
+// src/index.ts
+var ZERO_AGENT = {
+  runsStarted: 0,
+  runsSucceeded: 0,
+  runsFailed: 0,
+  runErrors: 0,
+  toolCalls: 0,
+  toolErrors: 0,
+  totalTokens: 0,
+  costTotal: 0
+};
+function zeroMetrics() {
+  return {
+    ...ZERO_AGENT,
+    runsEnded: 0,
+    operationsStarted: 0,
+    operationsEnded: 0,
+    operationErrors: 0,
+    taskCalls: 0,
+    taskErrors: 0,
+    ruleBlocks: 0,
+    ruleWarnings: 0,
+    compactedTokens: 0,
+    byAgent: {}
+  };
+}
+function redactEvent(event, options) {
+  if (options.redactToolArguments === false || event.type !== "tool_call") return event;
+  return { ...event, arguments: { redacted: true } };
+}
+function eventLevel(event) {
+  switch (event.type) {
+    case "log":
+      return event.level;
+    case "run_error":
+      return "error";
+    case "run_end":
+    case "operation_end":
+    case "tool_result":
+    case "task_end":
+      return event.ok ? "info" : "error";
+    case "rule_triggered":
+      return "warn";
+    case "text_delta":
+    case "thinking_delta":
+      return "debug";
+    default:
+      return "info";
+  }
+}
+function createJsonLogObserver(options = {}) {
+  const include = options.include ? new Set(options.include) : void 0;
+  const exclude = new Set(options.exclude ?? []);
+  const sink = options.sink ?? ((record) => console.log(JSON.stringify(record)));
+  const dropDeltas = !include && options.includeDeltas !== true;
+  return (raw) => {
+    if (include && !include.has(raw.type)) return;
+    if (exclude.has(raw.type)) return;
+    if (dropDeltas && (raw.type === "text_delta" || raw.type === "thinking_delta")) return;
+    const redacted = redactEvent(raw, options);
+    const event = options.sanitize ? options.sanitize(redacted) : redacted;
+    if (!event) return;
+    const record = {
+      timestamp: new Date(event.timestamp).toISOString(),
+      type: event.type,
+      level: eventLevel(event),
+      runId: event.runId,
+      session: event.session,
+      event
+    };
+    void Promise.resolve(sink(record)).catch(() => {
+    });
+  };
+}
+function createMetricsObserver() {
+  let metrics = zeroMetrics();
+  const runAgents = /* @__PURE__ */ new Map();
+  const forAgent = (agent) => {
+    if (!agent) return void 0;
+    metrics.byAgent[agent] ??= { ...ZERO_AGENT };
+    return metrics.byAgent[agent];
+  };
+  const runAgent = (event) => {
+    return event.runId ? forAgent(runAgents.get(event.runId)) : void 0;
+  };
+  return {
+    observe(event) {
+      switch (event.type) {
+        case "run_start": {
+          if (event.runId) runAgents.set(event.runId, event.agent);
+          metrics.runsStarted++;
+          forAgent(event.agent).runsStarted++;
+          break;
+        }
+        case "run_end": {
+          metrics.runsEnded++;
+          const agent = runAgent(event);
+          if (event.ok) {
+            metrics.runsSucceeded++;
+            if (agent) agent.runsSucceeded++;
+          } else {
+            metrics.runsFailed++;
+            if (agent) agent.runsFailed++;
+          }
+          if (event.runId) runAgents.delete(event.runId);
+          break;
+        }
+        case "run_error": {
+          metrics.runErrors++;
+          const agent = runAgent(event);
+          if (agent) agent.runErrors++;
+          break;
+        }
+        case "operation_start": {
+          metrics.operationsStarted++;
+          break;
+        }
+        case "operation_end": {
+          metrics.operationsEnded++;
+          if (!event.ok) metrics.operationErrors++;
+          break;
+        }
+        case "turn_end": {
+          metrics.totalTokens += event.usage.totalTokens;
+          metrics.costTotal += event.usage.costTotal;
+          const agent = runAgent(event);
+          if (agent) {
+            agent.totalTokens += event.usage.totalTokens;
+            agent.costTotal += event.usage.costTotal;
+          }
+          break;
+        }
+        case "tool_call": {
+          metrics.toolCalls++;
+          const agent = runAgent(event);
+          if (agent) agent.toolCalls++;
+          break;
+        }
+        case "tool_result": {
+          if (!event.ok) {
+            metrics.toolErrors++;
+            const agent = runAgent(event);
+            if (agent) agent.toolErrors++;
+          }
+          break;
+        }
+        case "task_start":
+          metrics.taskCalls++;
+          break;
+        case "task_end":
+          if (!event.ok) metrics.taskErrors++;
+          break;
+        case "rule_triggered":
+          if (event.action === "block") metrics.ruleBlocks++;
+          else metrics.ruleWarnings++;
+          break;
+        case "compaction":
+          metrics.compactedTokens += event.freedTokens;
+          break;
+        default:
+          break;
+      }
+    },
+    snapshot() {
+      return JSON.parse(JSON.stringify(metrics));
+    },
+    reset() {
+      metrics = zeroMetrics();
+      runAgents.clear();
+    }
+  };
+}
+export {
+  createJsonLogObserver,
+  createMetricsObserver
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@cybernetyx1/atlasflow-observability",
+  "version": "0.1.0",
+  "description": "JSON logging and in-process metrics observers for AtlasFlow event streams.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Cybernetyx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cybernetyx/atlasflow.git",
+    "directory": "packages/observability"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@cybernetyx1/atlasflow-runtime": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "valibot": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  }
+}