@aumos/agent-observability 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,107 @@
+/**
+ * HTTP client for the agent-observability API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentObservabilityClient } from "@aumos/agent-observability";
+ *
+ * const client = createAgentObservabilityClient({ baseUrl: "http://localhost:8080" });
+ *
+ * const traces = await client.getTraces({ agentId: "my-agent", limit: 50 });
+ * if (traces.ok) {
+ *   console.log(`Found ${traces.data.total} traces`);
+ * }
+ *
+ * const costs = await client.getCostReport({ agentId: "my-agent" });
+ * if (costs.ok) {
+ *   console.log(`Total cost: $${costs.data.total_cost_usd.toFixed(4)}`);
+ * }
+ * ```
+ */
+import type { AgentSpanKind, ApiResult, CostAttribution, DriftReport, FleetStatus, TraceExport, TraceListResponse } from "./types.js";
+/** Configuration options for the AgentObservabilityClient. */
+export interface AgentObservabilityClientConfig {
+    /** Base URL of the agent-observability server (e.g. "http://localhost:8080"). */
+    readonly baseUrl: string;
+    /** Optional request timeout in milliseconds (default: 30000). */
+    readonly timeoutMs?: number;
+    /** Optional extra HTTP headers sent with every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Typed HTTP client for the agent-observability server. */
+export interface AgentObservabilityClient {
+    /**
+     * Retrieve a paginated list of traces with optional filtering.
+     *
+     * Results are ordered by timestamp descending (most recent first).
+     * Use the `kind` filter to narrow to a specific agent span type such
+     * as "llm.call" or "tool.invoke".
+     *
+     * @param options - Optional filter parameters.
+     * @returns A TraceListResponse with matching traces and total count.
+     */
+    getTraces(options?: {
+        agentId?: string;
+        sessionId?: string;
+        kind?: AgentSpanKind;
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): Promise<ApiResult<TraceListResponse>>;
+    /**
+     * Retrieve aggregated cost attribution data.
+     *
+     * Returns cost breakdowns by model, provider, agent, and operation
+     * across all LLM calls matching the filter criteria.
+     *
+     * @param options - Optional filter parameters.
+     * @returns A CostAttribution record with per-dimension breakdowns.
+     */
+    getCostReport(options?: {
+        agentId?: string;
+        since?: number;
+        until?: number;
+    }): Promise<ApiResult<CostAttribution>>;
+    /**
+     * Run a behavioural drift analysis for an agent.
+     *
+     * Compares the agent's recent spans against the stored baseline using
+     * Z-score analysis. Returns a DriftReport with per-feature Z-scores
+     * and a qualitative severity label.
+     *
+     * @param agentId - The agent to analyse.
+     * @param options - Optional window and threshold parameters.
+     * @returns A DriftReport with drift status, Z-scores, and severity.
+     */
+    getDriftAnalysis(agentId: string, options?: {
+        windowSpans?: number;
+        sigmaThreshold?: number;
+    }): Promise<ApiResult<DriftReport>>;
+    /**
+     * Retrieve fleet-level health status for all tracked agents.
+     *
+     * Aggregates drift status, cost totals, and span counts per agent.
+     * Useful for dashboard views and alerting on fleet-wide anomalies.
+     *
+     * @returns A FleetStatus record with per-agent health summaries.
+     */
+    getFleetStatus(): Promise<ApiResult<FleetStatus>>;
+    /**
+     * Export all spans for a specific trace in OTLP-compatible JSON format.
+     *
+     * @param traceId - The OTel trace ID (hex string).
+     * @returns The full TraceExport with all child spans.
+     */
+    exportTraces(traceId: string): Promise<ApiResult<TraceExport>>;
+}
+/**
+ * Create a typed HTTP client for the agent-observability server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentObservabilityClient instance.
+ */
+export declare function createAgentObservabilityClient(config: AgentObservabilityClientConfig): AgentObservabilityClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,aAAa,EAEb,SAAS,EACT,eAAe,EACf,WAAW,EACX,WAAW,EACX,WAAW,EACX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAMpB,8DAA8D;AAC9D,MAAM,WAAW,8BAA8B;IAC7C,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AA0DD,4DAA4D;AAC5D,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;;OASG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,aAAa,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAE1C;;;;;;;;OAQG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC;IAExC;;;;;;;;;;OAUG;IACH,gBAAgB,CACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,GACA,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAEnC;;;;;;;OAOG;IACH,cAAc,IAAI,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAElD;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;CAChE;AAMD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,8BAA8B,GACrC,wBAAwB,CA4G1B"}

package/dist/client.js

@@ -0,0 +1,138 @@
+/**
+ * HTTP client for the agent-observability API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentObservabilityClient } from "@aumos/agent-observability";
+ *
+ * const client = createAgentObservabilityClient({ baseUrl: "http://localhost:8080" });
+ *
+ * const traces = await client.getTraces({ agentId: "my-agent", limit: 50 });
+ * if (traces.ok) {
+ *   console.log(`Found ${traces.data.total} traces`);
+ * }
+ *
+ * const costs = await client.getCostReport({ agentId: "my-agent" });
+ * if (costs.ok) {
+ *   console.log(`Total cost: $${costs.data.total_cost_usd.toFixed(4)}`);
+ * }
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function fetchJson(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        clearTimeout(timeoutId);
+        const body = await response.json();
+        if (!response.ok) {
+            const errorBody = body;
+            return {
+                ok: false,
+                error: {
+                    error: errorBody.error ?? "Unknown error",
+                    detail: errorBody.detail ?? "",
+                },
+                status: response.status,
+            };
+        }
+        return { ok: true, data: body };
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: { error: "Network error", detail: message },
+            status: 0,
+        };
+    }
+}
+function buildHeaders(extraHeaders) {
+    return {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...extraHeaders,
+    };
+}
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a typed HTTP client for the agent-observability server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentObservabilityClient instance.
+ */
+export function createAgentObservabilityClient(config) {
+    const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+    const baseHeaders = buildHeaders(extraHeaders);
+    return {
+        async getTraces(options = {}) {
+            const params = new URLSearchParams();
+            if (options.agentId !== undefined) {
+                params.set("agent_id", options.agentId);
+            }
+            if (options.sessionId !== undefined) {
+                params.set("session_id", options.sessionId);
+            }
+            if (options.kind !== undefined) {
+                params.set("kind", options.kind);
+            }
+            if (options.since !== undefined) {
+                params.set("since", String(options.since));
+            }
+            if (options.until !== undefined) {
+                params.set("until", String(options.until));
+            }
+            if (options.limit !== undefined) {
+                params.set("limit", String(options.limit));
+            }
+            const queryString = params.toString();
+            const url = queryString
+                ? `${baseUrl}/traces?${queryString}`
+                : `${baseUrl}/traces`;
+            return fetchJson(url, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async getCostReport(options = {}) {
+            const params = new URLSearchParams();
+            if (options.agentId !== undefined) {
+                params.set("agent_id", options.agentId);
+            }
+            if (options.since !== undefined) {
+                params.set("since", String(options.since));
+            }
+            if (options.until !== undefined) {
+                params.set("until", String(options.until));
+            }
+            const queryString = params.toString();
+            const url = queryString
+                ? `${baseUrl}/costs?${queryString}`
+                : `${baseUrl}/costs`;
+            return fetchJson(url, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async getDriftAnalysis(agentId, options = {}) {
+            const params = new URLSearchParams({ agent_id: agentId });
+            if (options.windowSpans !== undefined) {
+                params.set("window_spans", String(options.windowSpans));
+            }
+            if (options.sigmaThreshold !== undefined) {
+                params.set("sigma_threshold", String(options.sigmaThreshold));
+            }
+            return fetchJson(`${baseUrl}/drift/analysis?${params.toString()}`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async getFleetStatus() {
+            return fetchJson(`${baseUrl}/fleet/status`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async exportTraces(traceId) {
+            return fetchJson(`${baseUrl}/traces/${encodeURIComponent(traceId)}/export`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @aumos/agent-observability
+ *
+ * TypeScript client for the AumOS agent-observability framework.
+ * Provides distributed tracing, cost attribution, drift detection,
+ * and fleet health monitoring for AI agents.
+ */
+export type { AgentObservabilityClient, AgentObservabilityClientConfig, } from "./client.js";
+export { createAgentObservabilityClient } from "./client.js";
+export type { AgentSpanKind, AgentSpan, TraceExport, TraceListResponse, CostRecord, CostAttribution, DriftSeverity, DriftReport, AgentHealthSummary, FleetStatus, ApiError, ApiResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EACV,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAG7D,YAAY,EACV,aAAa,EACb,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,QAAQ,EACR,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @aumos/agent-observability
+ *
+ * TypeScript client for the AumOS agent-observability framework.
+ * Provides distributed tracing, cost attribution, drift detection,
+ * and fleet health monitoring for AI agents.
+ */
+export { createAgentObservabilityClient } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,223 @@
+/**
+ * TypeScript interfaces for the agent-observability framework.
+ *
+ * Mirrors the Python models defined in:
+ *   agent_observability.spans.types     — AgentSpanKind, AgentSpan
+ *   agent_observability.cost.tracker    — CostRecord, CostSummary
+ *   agent_observability.drift.detector  — DriftResult
+ *   agent_observability.server.models   — Trace, TraceListResponse
+ *
+ * All interfaces use readonly fields to match Python frozen models.
+ */
+/**
+ * The 8 semantic span kinds for agent observability.
+ * Maps to AgentSpanKind enum in agent_observability.spans.types.
+ *
+ * Span kind values follow the dot-separated naming convention used
+ * by the OpenTelemetry semantic conventions for agents:
+ *   - llm.call        — a single LLM request/response cycle
+ *   - tool.invoke     — an external tool or function call
+ *   - memory.read     — reading from any memory backend
+ *   - memory.write    — writing to any memory backend
+ *   - reasoning.step  — a single step in a chain-of-thought
+ *   - agent.delegate  — delegating a sub-task to another agent
+ *   - human.approval  — a human-in-the-loop approval gate
+ *   - agent.error     — a recoverable or unrecoverable agent error
+ */
+export type AgentSpanKind = "llm.call" | "tool.invoke" | "memory.read" | "memory.write" | "reasoning.step" | "agent.delegate" | "human.approval" | "agent.error";
+/**
+ * A single span within a trace, enriched with agent-semantic attributes.
+ * Combines the OTel span structure with agent-specific metadata.
+ */
+export interface AgentSpan {
+    /** OTel span ID (hex string). */
+    readonly span_id: string;
+    /** OTel trace ID this span belongs to (hex string). */
+    readonly trace_id: string;
+    /** Human-readable span name (e.g. "llm.call", "tool.invoke"). */
+    readonly name: string;
+    /** One of the 8 agent-semantic span kinds. */
+    readonly kind: AgentSpanKind;
+    /** Epoch milliseconds when the span started. */
+    readonly start_time_ms: number;
+    /** Epoch milliseconds when the span ended (null if still active). */
+    readonly end_time_ms: number | null;
+    /** Wall-clock duration in milliseconds (null if still active). */
+    readonly duration_ms: number | null;
+    /** Agent ID attached to this span. */
+    readonly agent_id: string;
+    /** Session ID attached to this span. */
+    readonly session_id: string;
+    /** Framework name (e.g. "langchain", "crewai"). */
+    readonly framework: string;
+    /** All OTel and agent-semantic attributes on the span. */
+    readonly attributes: Readonly<Record<string, string | number | boolean>>;
+}
+/**
+ * A complete exported trace — one root trace with all child spans.
+ * Maps to the trace response body from the observability server.
+ */
+export interface TraceExport {
+    /** OTel trace ID (hex string). */
+    readonly trace_id: string;
+    /** Primary agent ID for this trace. */
+    readonly agent_id: string;
+    /** Session identifier. */
+    readonly session_id: string;
+    /** Task or run identifier. */
+    readonly task_id: string;
+    /** Service or framework name. */
+    readonly service_name: string;
+    /** Ordered list of spans in this trace (root span first). */
+    readonly spans: readonly AgentSpan[];
+    /** Epoch unix timestamp (seconds) when the trace was recorded. */
+    readonly timestamp: number;
+    /** Arbitrary metadata attached to the trace. */
+    readonly tags: Readonly<Record<string, string>>;
+}
+/**
+ * Response body for the list-traces endpoint.
+ */
+export interface TraceListResponse {
+    readonly traces: readonly TraceExport[];
+    readonly total: number;
+}
+/**
+ * A single recorded LLM cost event.
+ * Maps to CostRecord in agent_observability.cost.tracker.
+ */
+export interface CostRecord {
+    /** Unix epoch timestamp (seconds) of this record. */
+    readonly timestamp: number;
+    /** Agent that made this LLM call. */
+    readonly agent_id: string;
+    /** Session this call belongs to. */
+    readonly session_id: string;
+    /** Task or run identifier. */
+    readonly task_id: string;
+    /** LLM provider name (e.g. "anthropic", "openai"). */
+    readonly provider: string;
+    /** Model name (e.g. "claude-sonnet-4-6", "gpt-4o"). */
+    readonly model: string;
+    /** Number of prompt/input tokens consumed. */
+    readonly input_tokens: number;
+    /** Number of completion/output tokens generated. */
+    readonly output_tokens: number;
+    /** Cached prompt tokens (charged at reduced rate by some providers). */
+    readonly cached_input_tokens: number;
+    /** Computed cost in USD. */
+    readonly cost_usd: number;
+    /** Semantic label for the operation (e.g. "llm_call", "embedding"). */
+    readonly operation: string;
+    /** OTel trace ID hex string. */
+    readonly trace_id: string;
+    /** OTel span ID hex string. */
+    readonly span_id: string;
+    /** Arbitrary key/value metadata. */
+    readonly tags: Readonly<Record<string, string>>;
+}
+/**
+ * Aggregated cost summary over a collection of CostRecord instances.
+ * Maps to CostSummary in agent_observability.cost.tracker.
+ */
+export interface CostAttribution {
+    /** Total cost in USD across all matching records. */
+    readonly total_cost_usd: number;
+    /** Total prompt/input tokens consumed. */
+    readonly total_input_tokens: number;
+    /** Total completion/output tokens generated. */
+    readonly total_output_tokens: number;
+    /** Combined token count. */
+    readonly total_tokens: number;
+    /** Number of cost records contributing to this summary. */
+    readonly record_count: number;
+    /** Cost breakdown by model name. */
+    readonly by_model: Readonly<Record<string, number>>;
+    /** Cost breakdown by provider name. */
+    readonly by_provider: Readonly<Record<string, number>>;
+    /** Cost breakdown by agent ID. */
+    readonly by_agent: Readonly<Record<string, number>>;
+    /** Cost breakdown by operation type. */
+    readonly by_operation: Readonly<Record<string, number>>;
+}
+/**
+ * Qualitative severity label for a drift event.
+ */
+export type DriftSeverity = "none" | "low" | "medium" | "high";
+/**
+ * Result of a single agent behaviour drift check.
+ * Maps to DriftResult in agent_observability.drift.detector.
+ */
+export interface DriftReport {
+    /** Agent ID that was checked. */
+    readonly agent_id: string;
+    /** Unix epoch timestamp (seconds) when the check ran. */
+    readonly timestamp: number;
+    /** True when at least one feature exceeded the Z-score threshold. */
+    readonly drifted: boolean;
+    /** Maximum absolute Z-score across all behavioural features. */
+    readonly max_z_score: number;
+    /** Configured sigma threshold used in this check. */
+    readonly threshold: number;
+    /** Feature names and their Z-scores for features that exceeded threshold. */
+    readonly drifted_features: Readonly<Record<string, number>>;
+    /** Z-scores for all behavioural features checked. */
+    readonly all_z_scores: Readonly<Record<string, number>>;
+    /** Age of the baseline in seconds at check time. */
+    readonly baseline_age_seconds: number;
+    /** Number of spans in the evaluation window. */
+    readonly window_span_count: number;
+    /** Qualitative severity label derived from max_z_score vs. threshold. */
+    readonly severity: DriftSeverity;
+    /** Optional human-readable notes (e.g. skip reason). */
+    readonly notes: string;
+}
+/**
+ * Per-agent health summary within the fleet status response.
+ */
+export interface AgentHealthSummary {
+    /** Agent identifier. */
+    readonly agent_id: string;
+    /** Whether this agent is currently drifting. */
+    readonly drifting: boolean;
+    /** Drift severity for this agent. */
+    readonly drift_severity: DriftSeverity;
+    /** Total cost attributed to this agent in USD. */
+    readonly total_cost_usd: number;
+    /** Total number of spans recorded for this agent. */
+    readonly span_count: number;
+    /** ISO-8601 UTC timestamp of the most recent span. */
+    readonly last_seen: string;
+}
+/**
+ * Fleet-level health status aggregating all tracked agents.
+ */
+export interface FleetStatus {
+    /** Total number of agents tracked. */
+    readonly agent_count: number;
+    /** Number of agents currently drifting. */
+    readonly drifting_count: number;
+    /** Cumulative cost across all agents in USD. */
+    readonly total_cost_usd: number;
+    /** Total span count across all agents. */
+    readonly total_span_count: number;
+    /** Per-agent health summaries. */
+    readonly agents: readonly AgentHealthSummary[];
+    /** ISO-8601 UTC timestamp when this status was generated. */
+    readonly generated_at: string;
+}
+/** Standard error payload returned by the agent-observability API. */
+export interface ApiError {
+    readonly error: string;
+    readonly detail: string;
+}
+/** Result type for all client operations. */
+export type ApiResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly error: ApiError;
+    readonly status: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * TypeScript interfaces for the agent-observability framework.
+ *
+ * Mirrors the Python models defined in:
+ *   agent_observability.spans.types     — AgentSpanKind, AgentSpan
+ *   agent_observability.cost.tracker    — CostRecord, CostSummary
+ *   agent_observability.drift.detector  — DriftResult
+ *   agent_observability.server.models   — Trace, TraceListResponse
+ *
+ * All interfaces use readonly fields to match Python frozen models.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@aumos/agent-observability",
+  "version": "0.1.0",
+  "description": "TypeScript client for the AumOS agent-observability framework — distributed tracing, cost attribution, and drift detection",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "aumos",
+    "agent-observability",
+    "opentelemetry",
+    "tracing",
+    "cost-attribution",
+    "drift-detection",
+    "llm-observability",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aumos-ai/agent-observability"
+  }
+}

package/src/client.ts

@@ -0,0 +1,301 @@
+/**
+ * HTTP client for the agent-observability API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentObservabilityClient } from "@aumos/agent-observability";
+ *
+ * const client = createAgentObservabilityClient({ baseUrl: "http://localhost:8080" });
+ *
+ * const traces = await client.getTraces({ agentId: "my-agent", limit: 50 });
+ * if (traces.ok) {
+ *   console.log(`Found ${traces.data.total} traces`);
+ * }
+ *
+ * const costs = await client.getCostReport({ agentId: "my-agent" });
+ * if (costs.ok) {
+ *   console.log(`Total cost: $${costs.data.total_cost_usd.toFixed(4)}`);
+ * }
+ * ```
+ */
+
+import type {
+  AgentSpanKind,
+  ApiError,
+  ApiResult,
+  CostAttribution,
+  DriftReport,
+  FleetStatus,
+  TraceExport,
+  TraceListResponse,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Client configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration options for the AgentObservabilityClient. */
+export interface AgentObservabilityClientConfig {
+  /** Base URL of the agent-observability server (e.g. "http://localhost:8080"). */
+  readonly baseUrl: string;
+  /** Optional request timeout in milliseconds (default: 30000). */
+  readonly timeoutMs?: number;
+  /** Optional extra HTTP headers sent with every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+async function fetchJson<T>(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<ApiResult<T>> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    const body = await response.json() as unknown;
+
+    if (!response.ok) {
+      const errorBody = body as Partial<ApiError>;
+      return {
+        ok: false,
+        error: {
+          error: errorBody.error ?? "Unknown error",
+          detail: errorBody.detail ?? "",
+        },
+        status: response.status,
+      };
+    }
+
+    return { ok: true, data: body as T };
+  } catch (err: unknown) {
+    clearTimeout(timeoutId);
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: { error: "Network error", detail: message },
+      status: 0,
+    };
+  }
+}
+
+function buildHeaders(
+  extraHeaders: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    ...extraHeaders,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Client interface
+// ---------------------------------------------------------------------------
+
+/** Typed HTTP client for the agent-observability server. */
+export interface AgentObservabilityClient {
+  /**
+   * Retrieve a paginated list of traces with optional filtering.
+   *
+   * Results are ordered by timestamp descending (most recent first).
+   * Use the `kind` filter to narrow to a specific agent span type such
+   * as "llm.call" or "tool.invoke".
+   *
+   * @param options - Optional filter parameters.
+   * @returns A TraceListResponse with matching traces and total count.
+   */
+  getTraces(options?: {
+    agentId?: string;
+    sessionId?: string;
+    kind?: AgentSpanKind;
+    since?: number;
+    until?: number;
+    limit?: number;
+  }): Promise<ApiResult<TraceListResponse>>;
+
+  /**
+   * Retrieve aggregated cost attribution data.
+   *
+   * Returns cost breakdowns by model, provider, agent, and operation
+   * across all LLM calls matching the filter criteria.
+   *
+   * @param options - Optional filter parameters.
+   * @returns A CostAttribution record with per-dimension breakdowns.
+   */
+  getCostReport(options?: {
+    agentId?: string;
+    since?: number;
+    until?: number;
+  }): Promise<ApiResult<CostAttribution>>;
+
+  /**
+   * Run a behavioural drift analysis for an agent.
+   *
+   * Compares the agent's recent spans against the stored baseline using
+   * Z-score analysis. Returns a DriftReport with per-feature Z-scores
+   * and a qualitative severity label.
+   *
+   * @param agentId - The agent to analyse.
+   * @param options - Optional window and threshold parameters.
+   * @returns A DriftReport with drift status, Z-scores, and severity.
+   */
+  getDriftAnalysis(
+    agentId: string,
+    options?: {
+      windowSpans?: number;
+      sigmaThreshold?: number;
+    },
+  ): Promise<ApiResult<DriftReport>>;
+
+  /**
+   * Retrieve fleet-level health status for all tracked agents.
+   *
+   * Aggregates drift status, cost totals, and span counts per agent.
+   * Useful for dashboard views and alerting on fleet-wide anomalies.
+   *
+   * @returns A FleetStatus record with per-agent health summaries.
+   */
+  getFleetStatus(): Promise<ApiResult<FleetStatus>>;
+
+  /**
+   * Export all spans for a specific trace in OTLP-compatible JSON format.
+   *
+   * @param traceId - The OTel trace ID (hex string).
+   * @returns The full TraceExport with all child spans.
+   */
+  exportTraces(traceId: string): Promise<ApiResult<TraceExport>>;
+}
+
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a typed HTTP client for the agent-observability server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentObservabilityClient instance.
+ */
+export function createAgentObservabilityClient(
+  config: AgentObservabilityClientConfig,
+): AgentObservabilityClient {
+  const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+  const baseHeaders = buildHeaders(extraHeaders);
+
+  return {
+    async getTraces(
+      options: {
+        agentId?: string;
+        sessionId?: string;
+        kind?: AgentSpanKind;
+        since?: number;
+        until?: number;
+        limit?: number;
+      } = {},
+    ): Promise<ApiResult<TraceListResponse>> {
+      const params = new URLSearchParams();
+      if (options.agentId !== undefined) {
+        params.set("agent_id", options.agentId);
+      }
+      if (options.sessionId !== undefined) {
+        params.set("session_id", options.sessionId);
+      }
+      if (options.kind !== undefined) {
+        params.set("kind", options.kind);
+      }
+      if (options.since !== undefined) {
+        params.set("since", String(options.since));
+      }
+      if (options.until !== undefined) {
+        params.set("until", String(options.until));
+      }
+      if (options.limit !== undefined) {
+        params.set("limit", String(options.limit));
+      }
+
+      const queryString = params.toString();
+      const url = queryString
+        ? `${baseUrl}/traces?${queryString}`
+        : `${baseUrl}/traces`;
+
+      return fetchJson<TraceListResponse>(
+        url,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async getCostReport(
+      options: { agentId?: string; since?: number; until?: number } = {},
+    ): Promise<ApiResult<CostAttribution>> {
+      const params = new URLSearchParams();
+      if (options.agentId !== undefined) {
+        params.set("agent_id", options.agentId);
+      }
+      if (options.since !== undefined) {
+        params.set("since", String(options.since));
+      }
+      if (options.until !== undefined) {
+        params.set("until", String(options.until));
+      }
+
+      const queryString = params.toString();
+      const url = queryString
+        ? `${baseUrl}/costs?${queryString}`
+        : `${baseUrl}/costs`;
+
+      return fetchJson<CostAttribution>(
+        url,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async getDriftAnalysis(
+      agentId: string,
+      options: { windowSpans?: number; sigmaThreshold?: number } = {},
+    ): Promise<ApiResult<DriftReport>> {
+      const params = new URLSearchParams({ agent_id: agentId });
+      if (options.windowSpans !== undefined) {
+        params.set("window_spans", String(options.windowSpans));
+      }
+      if (options.sigmaThreshold !== undefined) {
+        params.set("sigma_threshold", String(options.sigmaThreshold));
+      }
+
+      return fetchJson<DriftReport>(
+        `${baseUrl}/drift/analysis?${params.toString()}`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async getFleetStatus(): Promise<ApiResult<FleetStatus>> {
+      return fetchJson<FleetStatus>(
+        `${baseUrl}/fleet/status`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async exportTraces(traceId: string): Promise<ApiResult<TraceExport>> {
+      return fetchJson<TraceExport>(
+        `${baseUrl}/traces/${encodeURIComponent(traceId)}/export`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * @aumos/agent-observability
+ *
+ * TypeScript client for the AumOS agent-observability framework.
+ * Provides distributed tracing, cost attribution, drift detection,
+ * and fleet health monitoring for AI agents.
+ */
+
+// Client and configuration
+export type {
+  AgentObservabilityClient,
+  AgentObservabilityClientConfig,
+} from "./client.js";
+export { createAgentObservabilityClient } from "./client.js";
+
+// Core observability types
+export type {
+  AgentSpanKind,
+  AgentSpan,
+  TraceExport,
+  TraceListResponse,
+  CostRecord,
+  CostAttribution,
+  DriftSeverity,
+  DriftReport,
+  AgentHealthSummary,
+  FleetStatus,
+  ApiError,
+  ApiResult,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,261 @@
+/**
+ * TypeScript interfaces for the agent-observability framework.
+ *
+ * Mirrors the Python models defined in:
+ *   agent_observability.spans.types     — AgentSpanKind, AgentSpan
+ *   agent_observability.cost.tracker    — CostRecord, CostSummary
+ *   agent_observability.drift.detector  — DriftResult
+ *   agent_observability.server.models   — Trace, TraceListResponse
+ *
+ * All interfaces use readonly fields to match Python frozen models.
+ */
+
+// ---------------------------------------------------------------------------
+// Agent span semantic types
+// ---------------------------------------------------------------------------
+
+/**
+ * The 8 semantic span kinds for agent observability.
+ * Maps to AgentSpanKind enum in agent_observability.spans.types.
+ *
+ * Span kind values follow the dot-separated naming convention used
+ * by the OpenTelemetry semantic conventions for agents:
+ *   - llm.call        — a single LLM request/response cycle
+ *   - tool.invoke     — an external tool or function call
+ *   - memory.read     — reading from any memory backend
+ *   - memory.write    — writing to any memory backend
+ *   - reasoning.step  — a single step in a chain-of-thought
+ *   - agent.delegate  — delegating a sub-task to another agent
+ *   - human.approval  — a human-in-the-loop approval gate
+ *   - agent.error     — a recoverable or unrecoverable agent error
+ */
+export type AgentSpanKind =
+  | "llm.call"
+  | "tool.invoke"
+  | "memory.read"
+  | "memory.write"
+  | "reasoning.step"
+  | "agent.delegate"
+  | "human.approval"
+  | "agent.error";
+
+/**
+ * A single span within a trace, enriched with agent-semantic attributes.
+ * Combines the OTel span structure with agent-specific metadata.
+ */
+export interface AgentSpan {
+  /** OTel span ID (hex string). */
+  readonly span_id: string;
+  /** OTel trace ID this span belongs to (hex string). */
+  readonly trace_id: string;
+  /** Human-readable span name (e.g. "llm.call", "tool.invoke"). */
+  readonly name: string;
+  /** One of the 8 agent-semantic span kinds. */
+  readonly kind: AgentSpanKind;
+  /** Epoch milliseconds when the span started. */
+  readonly start_time_ms: number;
+  /** Epoch milliseconds when the span ended (null if still active). */
+  readonly end_time_ms: number | null;
+  /** Wall-clock duration in milliseconds (null if still active). */
+  readonly duration_ms: number | null;
+  /** Agent ID attached to this span. */
+  readonly agent_id: string;
+  /** Session ID attached to this span. */
+  readonly session_id: string;
+  /** Framework name (e.g. "langchain", "crewai"). */
+  readonly framework: string;
+  /** All OTel and agent-semantic attributes on the span. */
+  readonly attributes: Readonly<Record<string, string | number | boolean>>;
+}
+
+// ---------------------------------------------------------------------------
+// Trace export
+// ---------------------------------------------------------------------------
+
+/**
+ * A complete exported trace — one root trace with all child spans.
+ * Maps to the trace response body from the observability server.
+ */
+export interface TraceExport {
+  /** OTel trace ID (hex string). */
+  readonly trace_id: string;
+  /** Primary agent ID for this trace. */
+  readonly agent_id: string;
+  /** Session identifier. */
+  readonly session_id: string;
+  /** Task or run identifier. */
+  readonly task_id: string;
+  /** Service or framework name. */
+  readonly service_name: string;
+  /** Ordered list of spans in this trace (root span first). */
+  readonly spans: readonly AgentSpan[];
+  /** Epoch unix timestamp (seconds) when the trace was recorded. */
+  readonly timestamp: number;
+  /** Arbitrary metadata attached to the trace. */
+  readonly tags: Readonly<Record<string, string>>;
+}
+
+/**
+ * Response body for the list-traces endpoint.
+ */
+export interface TraceListResponse {
+  readonly traces: readonly TraceExport[];
+  readonly total: number;
+}
+
+// ---------------------------------------------------------------------------
+// Cost attribution
+// ---------------------------------------------------------------------------
+
+/**
+ * A single recorded LLM cost event.
+ * Maps to CostRecord in agent_observability.cost.tracker.
+ */
+export interface CostRecord {
+  /** Unix epoch timestamp (seconds) of this record. */
+  readonly timestamp: number;
+  /** Agent that made this LLM call. */
+  readonly agent_id: string;
+  /** Session this call belongs to. */
+  readonly session_id: string;
+  /** Task or run identifier. */
+  readonly task_id: string;
+  /** LLM provider name (e.g. "anthropic", "openai"). */
+  readonly provider: string;
+  /** Model name (e.g. "claude-sonnet-4-6", "gpt-4o"). */
+  readonly model: string;
+  /** Number of prompt/input tokens consumed. */
+  readonly input_tokens: number;
+  /** Number of completion/output tokens generated. */
+  readonly output_tokens: number;
+  /** Cached prompt tokens (charged at reduced rate by some providers). */
+  readonly cached_input_tokens: number;
+  /** Computed cost in USD. */
+  readonly cost_usd: number;
+  /** Semantic label for the operation (e.g. "llm_call", "embedding"). */
+  readonly operation: string;
+  /** OTel trace ID hex string. */
+  readonly trace_id: string;
+  /** OTel span ID hex string. */
+  readonly span_id: string;
+  /** Arbitrary key/value metadata. */
+  readonly tags: Readonly<Record<string, string>>;
+}
+
+/**
+ * Aggregated cost summary over a collection of CostRecord instances.
+ * Maps to CostSummary in agent_observability.cost.tracker.
+ */
+export interface CostAttribution {
+  /** Total cost in USD across all matching records. */
+  readonly total_cost_usd: number;
+  /** Total prompt/input tokens consumed. */
+  readonly total_input_tokens: number;
+  /** Total completion/output tokens generated. */
+  readonly total_output_tokens: number;
+  /** Combined token count. */
+  readonly total_tokens: number;
+  /** Number of cost records contributing to this summary. */
+  readonly record_count: number;
+  /** Cost breakdown by model name. */
+  readonly by_model: Readonly<Record<string, number>>;
+  /** Cost breakdown by provider name. */
+  readonly by_provider: Readonly<Record<string, number>>;
+  /** Cost breakdown by agent ID. */
+  readonly by_agent: Readonly<Record<string, number>>;
+  /** Cost breakdown by operation type. */
+  readonly by_operation: Readonly<Record<string, number>>;
+}
+
+// ---------------------------------------------------------------------------
+// Drift detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Qualitative severity label for a drift event.
+ */
+export type DriftSeverity = "none" | "low" | "medium" | "high";
+
+/**
+ * Result of a single agent behaviour drift check.
+ * Maps to DriftResult in agent_observability.drift.detector.
+ */
+export interface DriftReport {
+  /** Agent ID that was checked. */
+  readonly agent_id: string;
+  /** Unix epoch timestamp (seconds) when the check ran. */
+  readonly timestamp: number;
+  /** True when at least one feature exceeded the Z-score threshold. */
+  readonly drifted: boolean;
+  /** Maximum absolute Z-score across all behavioural features. */
+  readonly max_z_score: number;
+  /** Configured sigma threshold used in this check. */
+  readonly threshold: number;
+  /** Feature names and their Z-scores for features that exceeded threshold. */
+  readonly drifted_features: Readonly<Record<string, number>>;
+  /** Z-scores for all behavioural features checked. */
+  readonly all_z_scores: Readonly<Record<string, number>>;
+  /** Age of the baseline in seconds at check time. */
+  readonly baseline_age_seconds: number;
+  /** Number of spans in the evaluation window. */
+  readonly window_span_count: number;
+  /** Qualitative severity label derived from max_z_score vs. threshold. */
+  readonly severity: DriftSeverity;
+  /** Optional human-readable notes (e.g. skip reason). */
+  readonly notes: string;
+}
+
+// ---------------------------------------------------------------------------
+// Fleet status
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-agent health summary within the fleet status response.
+ */
+export interface AgentHealthSummary {
+  /** Agent identifier. */
+  readonly agent_id: string;
+  /** Whether this agent is currently drifting. */
+  readonly drifting: boolean;
+  /** Drift severity for this agent. */
+  readonly drift_severity: DriftSeverity;
+  /** Total cost attributed to this agent in USD. */
+  readonly total_cost_usd: number;
+  /** Total number of spans recorded for this agent. */
+  readonly span_count: number;
+  /** ISO-8601 UTC timestamp of the most recent span. */
+  readonly last_seen: string;
+}
+
+/**
+ * Fleet-level health status aggregating all tracked agents.
+ */
+export interface FleetStatus {
+  /** Total number of agents tracked. */
+  readonly agent_count: number;
+  /** Number of agents currently drifting. */
+  readonly drifting_count: number;
+  /** Cumulative cost across all agents in USD. */
+  readonly total_cost_usd: number;
+  /** Total span count across all agents. */
+  readonly total_span_count: number;
+  /** Per-agent health summaries. */
+  readonly agents: readonly AgentHealthSummary[];
+  /** ISO-8601 UTC timestamp when this status was generated. */
+  readonly generated_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// Error and result wrapper
+// ---------------------------------------------------------------------------
+
+/** Standard error payload returned by the agent-observability API. */
+export interface ApiError {
+  readonly error: string;
+  readonly detail: string;
+}
+
+/** Result type for all client operations. */
+export type ApiResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: ApiError; readonly status: number };

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}