@senad-d/observme 0.1.4 → 0.1.5

package/src/otel/traces.ts

@@ -3,15 +3,24 @@ import type { Resource } from "@opentelemetry/resources";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
 import type { Sampler, SpanExporter, SpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { BatchSpanProcessor, ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
+import {
+  AlwaysOffSampler,
+  BasicTracerProvider,
+  BatchSpanProcessor,
+  ParentBasedSampler,
+  TraceIdRatioBasedSampler,
+} from "@opentelemetry/sdk-trace-base";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import type { ObservMeConfig, TraceBatchConfig } from "../config/schema.ts";
 import { appendOtlpSignalPath } from "./otlp-endpoint.ts";
+import { buildOtlpHttpAgentOptions, type OtlpHttpAgentOptions } from "./otlp-http-options.ts";
 import type { StartOtelSdkFactoryOptions } from "./sdk.ts";
 
 export const OBSERVME_TRACER_NAME = "@senad-d/observme";
 export const OTLP_TRACE_SIGNAL_PATH = "/v1/traces";
 
+const noopTracer = new BasicTracerProvider({ sampler: new AlwaysOffSampler() }).getTracer(OBSERVME_TRACER_NAME);
+
 export const DOCUMENTED_TRACE_BATCH_DEFAULTS = {
   maxQueueSize: 2048,
   maxExportBatchSize: 512,
@@ -25,6 +34,7 @@ export interface OtlpTraceExporterOptions {
   readonly url: string;
   readonly headers: Record<string, string>;
   readonly timeoutMillis: number;
+  readonly httpAgentOptions: OtlpHttpAgentOptions;
 }
 
 export interface TraceProviderOptions {
@@ -35,7 +45,6 @@ export interface TraceProviderOptions {
 }
 
 export interface TraceProviderLike {
-  register?: () => void;
   getTracer: (name: string) => Tracer;
   forceFlush?: () => Promise<void> | void;
   shutdown?: () => Promise<void> | void;
@@ -48,7 +57,6 @@ export type TraceProviderFactory = (options: TraceProviderOptions) => TraceProvi
 export interface ObservMeTraceSdkOptions {
   readonly config: ObservMeConfig;
   readonly tracerName?: string;
-  readonly registerGlobal?: boolean;
   readonly exporterFactory?: TraceExporterFactory;
   readonly spanProcessorFactory?: TraceSpanProcessorFactory;
   readonly tracerProviderFactory?: TraceProviderFactory;
@@ -63,18 +71,18 @@ export interface TraceExporterWiring {
 export class ObservMeTraceSdk {
   readonly #config: ObservMeConfig;
   readonly #tracerName: string;
-  readonly #registerGlobal: boolean;
   readonly #exporterFactory: TraceExporterFactory;
   readonly #spanProcessorFactory: TraceSpanProcessorFactory;
   readonly #tracerProviderFactory: TraceProviderFactory;
+  #exporter?: SpanExporter;
+  #processor?: SpanProcessor;
   #provider?: TraceProviderLike;
-  #tracer?: Tracer;
+  #tracer: Tracer = noopTracer;
   #state: TracePipelineState = "idle";
 
   constructor(options: ObservMeTraceSdkOptions) {
     this.#config = options.config;
     this.#tracerName = options.tracerName ?? OBSERVME_TRACER_NAME;
-    this.#registerGlobal = options.registerGlobal ?? true;
     this.#exporterFactory = options.exporterFactory ?? createOtlpTraceExporter;
     this.#spanProcessorFactory = options.spanProcessorFactory ?? createBatchSpanProcessor;
     this.#tracerProviderFactory = options.tracerProviderFactory ?? createNodeTraceProvider;
@@ -84,28 +92,27 @@ export class ObservMeTraceSdk {
     return this.#state;
   }
 
-  get tracer(): Tracer | undefined {
+  get tracer(): Tracer {
     return this.#tracer;
   }
 
   start(): void {
     if (this.#state === "started" || this.#state === "disabled") return;
-    if (!this.#config.traces.enabled) {
+    if (!this.#config.enabled || !this.#config.traces.enabled) {
       this.#state = "disabled";
       return;
     }
 
     const wiring = buildTraceExporterWiring(this.#config);
-    const exporter = this.#exporterFactory(wiring.exporter);
-    const processor = this.#spanProcessorFactory(exporter, wiring.batch);
+    this.#exporter = this.#exporterFactory(wiring.exporter);
+    this.#processor = this.#spanProcessorFactory(this.#exporter, wiring.batch);
     this.#provider = this.#tracerProviderFactory({
       resource: createTraceResource(this.#config),
       sampler: createTraceSampler(this.#config),
-      spanProcessors: [processor],
+      spanProcessors: [this.#processor],
       forceFlushTimeoutMillis: this.#config.shutdown.flushTimeoutMs,
     });
 
-    if (this.#registerGlobal) this.#provider.register?.();
     this.#tracer = this.#provider.getTracer(this.#tracerName);
     this.#state = "started";
   }
@@ -115,9 +122,19 @@ export class ObservMeTraceSdk {
   }
 
   async shutdown(): Promise<void> {
-    await this.#provider?.shutdown?.();
-    this.#state = "shutdown";
-    this.#tracer = undefined;
+    if (this.#state === "shutdown") return;
+
+    try {
+      if (this.#provider?.shutdown) await this.#provider.shutdown();
+      else if (this.#processor) await this.#processor.shutdown();
+      else await this.#exporter?.shutdown();
+    } finally {
+      this.#provider = undefined;
+      this.#processor = undefined;
+      this.#exporter = undefined;
+      this.#state = "shutdown";
+      this.#tracer = noopTracer;
+    }
   }
 }
 
@@ -127,7 +144,7 @@ export function createTraceSessionScopedOtelSdk(options: StartOtelSdkFactoryOpti
 
 export function buildTraceExporterWiring(config: ObservMeConfig): TraceExporterWiring {
   return {
-    enabled: config.traces.enabled,
+    enabled: config.enabled && config.traces.enabled,
     exporter: buildOtlpTraceExporterOptions(config),
     batch: { ...config.traces.batch },
   };
@@ -138,6 +155,7 @@ export function buildOtlpTraceExporterOptions(config: ObservMeConfig): OtlpTrace
     url: resolveTraceEndpoint(config),
     headers: { ...config.otlp.headers },
     timeoutMillis: config.otlp.timeoutMs,
+    httpAgentOptions: buildOtlpHttpAgentOptions(config),
   };
 }
 

package/src/pi/agent-tree-tracker.ts

@@ -48,6 +48,7 @@ interface MutableAgentTreeNode {
 }
 
 const activeChildStatuses = new Set<AgentChildStatus>(["starting", "active"]);
+const terminalChildStatuses = new Set<AgentChildStatus>(["completed", "failed", "cancelled", "orphaned"]);
 const agentStatusOrder: AgentChildStatus[] = ["starting", "active", "completed", "failed", "cancelled", "orphaned"];
 
 export class AgentTreeTracker {
@@ -68,6 +69,11 @@ export class AgentTreeTracker {
   }
 
   registerAgent(lineage: AgentLineageContext, status: AgentChildStatus = "active"): AgentTreeNode {
+    const existingNode = this.#nodes.get(lineage.agentId);
+    if (existingNode && !isAgentStatusTransitionAllowed(existingNode.status, status)) {
+      return snapshotNode(existingNode, this.#nodes);
+    }
+
     const node = createMutableNode(lineage, status, this.isOrphan(lineage));
     this.retainParentForInsertion(node.parentAgentId);
     this.#nodes.set(lineage.agentId, node);
@@ -77,7 +83,7 @@ export class AgentTreeTracker {
 
   updateStatus(agentId: string, status: AgentChildStatus): AgentTreeNode | undefined {
     const node = this.#nodes.get(agentId);
-    if (!node) return undefined;
+    if (!node || !isAgentStatusTransitionAllowed(node.status, status)) return undefined;
 
     node.status = status;
     if (status === "orphaned") node.orphaned = true;
@@ -177,6 +183,13 @@ export class AgentTreeTracker {
   }
 }
 
+export function isAgentStatusTransitionAllowed(current: AgentChildStatus, next: AgentChildStatus): boolean {
+  if (current === next) return true;
+  if (terminalChildStatuses.has(current)) return false;
+  if (current === "starting") return true;
+  return next !== "starting";
+}
+
 export function assertNoHighCardinalityMetricLabels(labels: Record<string, string>): void {
   const forbiddenKey = Object.keys(labels).find(isHighCardinalityLineageKey);
   if (forbiddenKey) throw new Error(`High-cardinality lineage value must not be used as a metric label: ${forbiddenKey}`);

package/src/pi/compatibility.ts

@@ -0,0 +1,121 @@
+import { VERSION as PI_VERSION } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export const MINIMUM_SUPPORTED_PI_VERSION = "0.80.5";
+export const RELEASE_TESTED_PI_VERSION = "0.80.6";
+const FIRST_UNSUPPORTED_PI_VERSION = "0.81.0";
+export const SUPPORTED_PI_VERSION_RANGE =
+  `>=${MINIMUM_SUPPORTED_PI_VERSION} <${FIRST_UNSUPPORTED_PI_VERSION}`;
+
+const compatibilityErrorPrefix = "ObservMe/Pi API compatibility error";
+const MAX_DETECTED_PI_VERSION_LENGTH = 128;
+const piVersionCorePattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
+const semanticVersionIdentifierPattern = /^[0-9A-Za-z-]+$/u;
+const numericIdentifierPattern = /^\d+$/u;
+const requiredPiMethods = ["on", "registerCommand", "appendEntry", "getThinkingLevel"] as const;
+
+export function assertObservMePiCompatibility(
+  pi: unknown,
+  piVersion = PI_VERSION,
+): asserts pi is ExtensionAPI {
+  const missingMethods = findMissingPiMethods(pi);
+  const detectedVersion = normalizeDetectedVersion(piVersion);
+  const versionSupported = isSupportedPiVersion(detectedVersion);
+  if (versionSupported && missingMethods.length === 0) return;
+
+  const reasons: string[] = [];
+  if (!versionSupported) reasons.push(`detected Pi ${detectedVersion}`);
+  if (missingMethods.length > 0) reasons.push(`missing required API method(s): ${missingMethods.join(", ")}`);
+
+  throw new TypeError(
+    `${compatibilityErrorPrefix}: ObservMe requires @earendil-works/pi-coding-agent ${SUPPORTED_PI_VERSION_RANGE}; ${reasons.join("; ")}. No ObservMe event handlers or commands were registered.`,
+  );
+}
+
+function findMissingPiMethods(pi: unknown): string[] {
+  if (!isRecord(pi)) return [...requiredPiMethods];
+
+  const missing: string[] = [];
+  for (const method of requiredPiMethods) {
+    if (typeof pi[method] !== "function") missing.push(method);
+  }
+  return missing;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function normalizeDetectedVersion(value: unknown): string {
+  if (typeof value !== "string") return "unknown";
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_DETECTED_PI_VERSION_LENGTH) return "unknown";
+  return parsePiVersion(trimmed) ? trimmed : "unknown";
+}
+
+function isSupportedPiVersion(version: string): boolean {
+  const detected = parsePiVersion(version);
+  const minimum = parsePiVersion(MINIMUM_SUPPORTED_PI_VERSION);
+  const maximum = parsePiVersion(FIRST_UNSUPPORTED_PI_VERSION);
+  if (!detected || detected.prerelease || !minimum || !maximum) return false;
+
+  return comparePiVersions(detected, minimum) >= 0 && comparePiVersions(detected, maximum) < 0;
+}
+
+interface PiVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease?: string;
+}
+
+function parsePiVersion(version: string): PiVersion | undefined {
+  const buildSeparatorIndex = version.indexOf("+");
+  const versionAndPrerelease = buildSeparatorIndex === -1 ? version : version.slice(0, buildSeparatorIndex);
+  const build = buildSeparatorIndex === -1 ? undefined : version.slice(buildSeparatorIndex + 1);
+  if (build !== undefined && !hasValidSemanticVersionIdentifiers(build, true)) return undefined;
+
+  const prereleaseSeparatorIndex = versionAndPrerelease.indexOf("-");
+  const coreVersion = prereleaseSeparatorIndex === -1
+    ? versionAndPrerelease
+    : versionAndPrerelease.slice(0, prereleaseSeparatorIndex);
+  const prerelease = prereleaseSeparatorIndex === -1
+    ? undefined
+    : versionAndPrerelease.slice(prereleaseSeparatorIndex + 1);
+  if (prerelease !== undefined && !hasValidSemanticVersionIdentifiers(prerelease, false)) return undefined;
+
+  const match = piVersionCorePattern.exec(coreVersion);
+  if (!match) return undefined;
+
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  const patch = Number(match[3]);
+  if (!Number.isSafeInteger(major) || !Number.isSafeInteger(minor) || !Number.isSafeInteger(patch)) {
+    return undefined;
+  }
+
+  return {
+    major,
+    minor,
+    patch,
+    ...(prerelease === undefined ? {} : { prerelease }),
+  };
+}
+
+function hasValidSemanticVersionIdentifiers(value: string, allowLeadingZeros: boolean): boolean {
+  for (const identifier of value.split(".")) {
+    if (!semanticVersionIdentifierPattern.test(identifier)) return false;
+    if (!allowLeadingZeros && hasInvalidNumericIdentifier(identifier)) return false;
+  }
+  return true;
+}
+
+function hasInvalidNumericIdentifier(identifier: string): boolean {
+  return identifier.length > 1 && identifier.startsWith("0") && numericIdentifierPattern.test(identifier);
+}
+
+function comparePiVersions(left: PiVersion, right: PiVersion): number {
+  if (left.major !== right.major) return left.major - right.major;
+  if (left.minor !== right.minor) return left.minor - right.minor;
+  return left.patch - right.patch;
+}

package/src/pi/event-handlers/agent-turn.ts

@@ -1,4 +1,11 @@
 import { SpanStatusCode } from "@opentelemetry/api";
+import type {
+  AgentEndEvent,
+  AgentStartEvent,
+  ExtensionContext,
+  TurnEndEvent,
+  TurnStartEvent,
+} from "@earendil-works/pi-coding-agent";
 import { recordObsSessionTurn } from "../../commands/obs-session.ts";
 import { AGENT_RUN_ATTRIBUTES, TURN_ATTRIBUTES } from "../../semconv/attributes.ts";
 import { LOG_EVENT_NAMES } from "../../semconv/metrics.ts";
@@ -21,7 +28,7 @@ import {
 } from "../handler-internals.ts";
 import { workflowFailed } from "../handler-runtime.ts";
 import type { HandlerRegistrar } from "../handler-runtime.ts";
-import type { Handler, HandlerSessionState, ObservMeHandlerContext } from "../handler-types.ts";
+import type { HandlerSessionState, PiHandler } from "../handler-types.ts";
 
 export function registerAgentTurnHandlers(registrar: HandlerRegistrar, state: HandlerSessionState): void {
   registrar.add("agent_start", createAgentStartHandler(state));
@@ -30,11 +37,11 @@ export function registerAgentTurnHandlers(registrar: HandlerRegistrar, state: Ha
   registrar.add("agent_end", createAgentEndHandler(state));
 }
 
-function createAgentStartHandler(state: HandlerSessionState): Handler {
+function createAgentStartHandler(state: HandlerSessionState): PiHandler<"agent_start"> {
   return handleAgentStart.bind(undefined, state);
 }
 
-function handleAgentStart(state: HandlerSessionState, event: unknown, _ctx: ObservMeHandlerContext): void {
+function handleAgentStart(state: HandlerSessionState, event: AgentStartEvent, _ctx: ExtensionContext): void {
   const session = state.session;
   if (!session) return;
 
@@ -48,11 +55,11 @@ function handleAgentStart(state: HandlerSessionState, event: unknown, _ctx: Obse
   emitLifecycleLog(session.logger, LOG_EVENT_NAMES.AGENT_RUN_STARTED, attributes);
 }
 
-function createAgentEndHandler(state: HandlerSessionState): Handler {
+function createAgentEndHandler(state: HandlerSessionState): PiHandler<"agent_end"> {
   return handleAgentEnd.bind(undefined, state);
 }
 
-function handleAgentEnd(state: HandlerSessionState, event: unknown, _ctx: ObservMeHandlerContext): void {
+function handleAgentEnd(state: HandlerSessionState, event: AgentEndEvent, _ctx: ExtensionContext): void {
   const session = state.session;
   if (!session) return;
 
@@ -75,11 +82,11 @@ function handleAgentEnd(state: HandlerSessionState, event: unknown, _ctx: Observ
   });
 }
 
-function createTurnStartHandler(state: HandlerSessionState): Handler {
+function createTurnStartHandler(state: HandlerSessionState): PiHandler<"turn_start"> {
   return handleTurnStart.bind(undefined, state);
 }
 
-function handleTurnStart(state: HandlerSessionState, event: unknown, _ctx: ObservMeHandlerContext): void {
+function handleTurnStart(state: HandlerSessionState, event: TurnStartEvent, _ctx: ExtensionContext): void {
   const session = state.session;
   if (!session) return;
 
@@ -99,11 +106,11 @@ function handleTurnStart(state: HandlerSessionState, event: unknown, _ctx: Obser
   emitLifecycleLog(session.logger, LOG_EVENT_NAMES.TURN_STARTED, attributes);
 }
 
-function createTurnEndHandler(state: HandlerSessionState): Handler {
+function createTurnEndHandler(state: HandlerSessionState): PiHandler<"turn_end"> {
   return handleTurnEnd.bind(undefined, state);
 }
 
-function handleTurnEnd(state: HandlerSessionState, event: unknown, _ctx: ObservMeHandlerContext): void {
+function handleTurnEnd(state: HandlerSessionState, event: TurnEndEvent, _ctx: ExtensionContext): void {
   const session = state.session;
   if (!session) return;