@senad-d/observme 0.1.0

package/src/pi/handler-types.ts

@@ -0,0 +1,261 @@
+import type { Counter, Histogram, Meter, Span, Tracer, UpDownCounter } from "@opentelemetry/api";
+import type { Logger } from "@opentelemetry/api-logs";
+import type { EnsureProjectConfig as BootstrapEnsureProjectConfig } from "../config/bootstrap-project-config.ts";
+import type {
+  LoadSessionConfigOptions,
+  LoadSessionConfigResult,
+  SessionConfigDiagnostics,
+} from "../config/load-config.ts";
+import type { ObservMeConfig } from "../config/schema.ts";
+import type { ObservMeLogSdk } from "../otel/logs.ts";
+import type { ObservMeMetricSdk } from "../otel/metrics.ts";
+import type { ObservMeOtelSdkController } from "../otel/sdk.ts";
+import type { ObservMeTraceSdk } from "../otel/traces.ts";
+import type { BoundedMap } from "../util/bounded-map.ts";
+import type { AgentLineageContext } from "./agent-lineage.ts";
+import type { AgentTreeTracker } from "./agent-tree-tracker.ts";
+import type {
+  AgentWaitJoinState,
+  ChildFailureAccountingState,
+  SubagentSpawnState,
+} from "./subagent-types.ts";
+
+export type AttributePrimitive = boolean | number | string | string[];
+export type AttributeMap = Record<string, AttributePrimitive>;
+export type TelemetryMeter = Pick<Meter, "createCounter" | "createHistogram" | "createUpDownCounter">;
+export type TelemetryTracer = Pick<Tracer, "startSpan">;
+export type TelemetryLogger = Pick<Logger, "emit">;
+export type Handler = (event: unknown, ctx: ObservMeHandlerContext) => Promise<void> | void;
+export type HandlerErrorRecorder = (name: string, error: unknown) => void;
+export type LoadSessionConfig = (
+  options: LoadSessionConfigOptions,
+) => Promise<ObservMeConfig | LoadSessionConfigResult>;
+export type StartSessionTelemetry = (options: StartSessionTelemetryOptions) => Promise<ObservMeTelemetrySession>;
+export type ReadSessionHeader = (sessionFile: string) => Promise<SessionRecoveryHeader | undefined>;
+export type EnsureProjectConfig = BootstrapEnsureProjectConfig;
+
+export interface MinimalSessionCorrelation {
+  readonly workflowId?: string;
+  readonly agentId?: string;
+  readonly parentAgentId?: string;
+  readonly rootAgentId?: string;
+  readonly parentSessionId?: string;
+  readonly depth?: number;
+  readonly spawnId?: string;
+  readonly capability?: string;
+}
+
+export interface SessionRecoveryHeader {
+  readonly type?: string;
+  readonly version?: number | string;
+  readonly id?: string;
+  readonly timestamp?: string;
+  readonly cwd?: string;
+  readonly parentSession?: string;
+  readonly correlation?: MinimalSessionCorrelation;
+}
+
+export interface StartupRecoveryState {
+  readonly resumed: boolean;
+  readonly sessionFile?: string;
+  readonly header?: SessionRecoveryHeader;
+  readonly customCorrelation?: MinimalSessionCorrelation;
+}
+
+export interface ObservMeHandlerContext {
+  readonly cwd?: string;
+  readonly hasUI?: boolean;
+  readonly sessionFile?: string;
+  readonly session_file?: string;
+  readonly sessionId?: string;
+  readonly session_id?: string;
+  readonly model?: unknown;
+  readonly thinking?: unknown;
+  readonly ui?: {
+    notify?: (message: string, level?: "warning" | "info" | "error") => Promise<void> | void;
+    setStatus?: (key: string, value: string | undefined) => Promise<void> | void;
+  };
+  readonly isProjectTrusted?: () => boolean | Promise<boolean>;
+  readonly [key: string]: unknown;
+}
+
+export interface ObservMePiApi {
+  on: (eventName: string, handler: Handler) => void;
+}
+
+export interface RegisterHandlersOptions {
+  readonly loadConfig?: LoadSessionConfig;
+  readonly startTelemetry?: StartSessionTelemetry;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly now?: () => number;
+  readonly configDirName?: string;
+  readonly trustedParentContext?: boolean;
+  readonly requireCompleteParentEnvelope?: boolean;
+  readonly readSessionHeader?: ReadSessionHeader;
+  readonly ensureProjectConfig?: EnsureProjectConfig;
+  readonly onHandlerError?: HandlerErrorRecorder;
+}
+
+export interface StartSessionTelemetryOptions {
+  readonly config: ObservMeConfig;
+  readonly lineage: AgentLineageContext;
+  readonly now?: () => number;
+}
+
+export interface TurnSequenceRegistry {
+  readonly size: number;
+  get: (runId: string) => number | undefined;
+  set: (runId: string, sequence: number) => unknown;
+  delete: (runId: string) => boolean;
+  clear: () => void;
+}
+
+export interface ObservMeTelemetrySession {
+  readonly config: ObservMeConfig;
+  readonly lineage: AgentLineageContext;
+  readonly controller: Pick<ObservMeOtelSdkController, "flush" | "shutdown">;
+  readonly tracer: TelemetryTracer;
+  readonly meter: TelemetryMeter;
+  readonly logger: TelemetryLogger;
+  readonly metrics: ObservMeMetrics;
+  readonly spans: SpanRegistry;
+  agentTree: AgentTreeTracker;
+  sessionSpan?: Span;
+  sessionAttributes?: AttributeMap;
+  workflowStartedAtMs?: number;
+  now?: () => number;
+  activeAgentRecorded: boolean;
+  currentAgentRunId?: string;
+  currentTurnId?: string;
+  currentLlmRequestId?: string;
+  currentToolCallId?: string;
+  pendingUserBash?: PendingBashOperationState;
+  currentBranchPreparation?: BranchPreparationState;
+  agentRunSequence: number;
+  llmRequestSequence: number;
+  toolCallSequence: number;
+  turnSequences: TurnSequenceRegistry;
+  childFailureAccounting?: BoundedMap<string, ChildFailureAccountingState>;
+}
+
+export interface ObservMeMetrics {
+  readonly handlerErrors: Counter;
+  readonly telemetryDropped: Counter;
+  readonly exportErrors: Counter;
+  readonly sessionsStarted: Counter;
+  readonly sessionsShutdown: Counter;
+  readonly workflowsStarted: Counter;
+  readonly workflowsCompleted: Counter;
+  readonly workflowErrors: Counter;
+  readonly agentRuns: Counter;
+  readonly agentRunErrors: Counter;
+  readonly turnsStarted: Counter;
+  readonly turnsCompleted: Counter;
+  readonly llmRequests: Counter;
+  readonly llmErrors: Counter;
+  readonly llmInputTokens: Counter;
+  readonly llmOutputTokens: Counter;
+  readonly llmCacheReadTokens: Counter;
+  readonly llmCacheWriteTokens: Counter;
+  readonly llmCacheWrite1hTokens: Counter;
+  readonly llmReasoningTokens: Counter;
+  readonly llmTotalTokens: Counter;
+  readonly llmCostUsd: Counter;
+  readonly toolCalls: Counter;
+  readonly toolFailures: Counter;
+  readonly bashExecutions: Counter;
+  readonly bashFailures: Counter;
+  readonly modelChanges: Counter;
+  readonly thinkingLevelChanges: Counter;
+  readonly compactions: Counter;
+  readonly branches: Counter;
+  readonly subagentsSpawned: Counter;
+  readonly subagentSpawnFailures: Counter;
+  readonly orphanAgents: Counter;
+  readonly traceContextPropagationFailures: Counter;
+  readonly childAgentFailures: Counter;
+  readonly parentRecoveredFromChildFailure: Counter;
+  readonly redactionFailures: Counter;
+  readonly eventsObserved: Counter;
+  readonly activeSpans: UpDownCounter;
+  readonly activeAgents: UpDownCounter;
+  readonly workflowDurationMs: Histogram;
+  readonly agentRunDurationMs: Histogram;
+  readonly agentLifetimeDurationMs: Histogram;
+  readonly subagentSpawnDurationMs: Histogram;
+  readonly agentFanoutCount: Histogram;
+  readonly agentTreeDepth: Histogram;
+  readonly agentTreeWidth: Histogram;
+  readonly agentWaitDurationMs: Histogram;
+  readonly agentJoinDurationMs: Histogram;
+  readonly turnDurationMs: Histogram;
+  readonly llmRequestDurationMs: Histogram;
+  readonly toolDurationMs: Histogram;
+  readonly bashDurationMs: Histogram;
+  readonly compactionTokensBefore: Histogram;
+  readonly promptSizeChars: Histogram;
+  readonly responseSizeChars: Histogram;
+  readonly toolResultSizeChars: Histogram;
+  readonly handlerDurationMs: Histogram;
+  readonly genAiClientTokenUsage: Histogram;
+  readonly genAiClientOperationDuration: Histogram;
+}
+
+export interface SpanRegistry {
+  readonly activeAgentRuns: BoundedMap<string, Span>;
+  readonly activeTurns: BoundedMap<string, Span>;
+  readonly activeLlmRequests: BoundedMap<string, Span>;
+  readonly activeToolCalls: BoundedMap<string, ToolCallState>;
+  readonly activeSubagentSpawns: BoundedMap<string, SubagentSpawnState>;
+  readonly activeAgentWaits: BoundedMap<string, AgentWaitJoinState>;
+  readonly activeAgentJoins: BoundedMap<string, AgentWaitJoinState>;
+}
+
+export interface CapturedContent {
+  readonly value: string;
+  readonly truncated: boolean;
+  readonly originalLength?: number;
+}
+
+export interface ToolCallState {
+  readonly span: Span;
+  labels: Record<string, string>;
+  completionLogAttributes: AttributeMap;
+  capturedResult?: CapturedContent;
+}
+
+export interface PendingBashOperationState {
+  readonly span: Span;
+  readonly startedAtMs: number;
+  readonly eventStartedAtMs?: number;
+}
+
+export interface BranchPreparationState {
+  readonly targetId?: string;
+  readonly oldLeafId?: string;
+  readonly commonAncestorId?: string;
+  readonly pathHash?: string;
+}
+
+export interface CompositeOtelSignalSdk {
+  readonly traceSdk: ObservMeTraceSdk;
+  readonly metricSdk: ObservMeMetricSdk;
+  readonly logSdk: ObservMeLogSdk;
+  start: () => void;
+  forceFlush: () => Promise<void>;
+  shutdown: () => Promise<void>;
+}
+
+export interface HandlerSessionState {
+  session?: ObservMeTelemetrySession;
+}
+
+export interface HandlerRegistration {
+  readonly eventName: string;
+  readonly handler: Handler;
+}
+
+export interface SessionConfigLoadResult {
+  readonly config: ObservMeConfig;
+  readonly diagnostics?: SessionConfigDiagnostics;
+}

package/src/pi/handlers.ts

@@ -0,0 +1,75 @@
+import { registerAgentTurnHandlers } from "./event-handlers/agent-turn.ts";
+import { registerLifecycleHandlers } from "./event-handlers/lifecycle.ts";
+import { registerLlmHandlers } from "./event-handlers/llm.ts";
+import { registerSessionEventHandlers } from "./event-handlers/session-events.ts";
+import { registerToolBashHandlers } from "./event-handlers/tool-bash.ts";
+import {
+  HandlerRegistrar,
+  SerializedLifecycleQueue,
+  createStatefulHandlerErrorRecorder,
+  resolveObservMePiApi,
+  setDefaultHandlerErrorRecorder,
+} from "./handler-runtime.ts";
+import type { HandlerSessionState, RegisterHandlersOptions } from "./handler-types.ts";
+
+export { buildSessionAttributes, readSessionHeaderFromFile } from "./event-handlers/lifecycle.ts";
+export { deriveTurnId, emitLifecycleLog } from "./handler-internals.ts";
+export {
+  OBSERVME_SEMCONV_VERSION,
+  buildTelemetryInstanceResourceAttributes,
+  createAgentTreeTracker,
+  createCompositeOtelSignalSdk,
+  createHistogram,
+  createObservMeMetrics,
+  createSpanRegistry,
+  createTurnSequenceRegistry,
+  isRootWorkflow,
+  safeHandler,
+  startSessionTelemetry,
+  withTelemetrySessionResourceAttributes,
+  workflowFailed,
+} from "./handler-runtime.ts";
+export type {
+  AttributeMap,
+  AttributePrimitive,
+  BranchPreparationState,
+  CompositeOtelSignalSdk,
+  EnsureProjectConfig,
+  Handler,
+  HandlerErrorRecorder,
+  LoadSessionConfig,
+  MinimalSessionCorrelation,
+  ObservMeHandlerContext,
+  ObservMeMetrics,
+  ObservMePiApi,
+  ObservMeTelemetrySession,
+  PendingBashOperationState,
+  ReadSessionHeader,
+  RegisterHandlersOptions,
+  SessionRecoveryHeader,
+  SpanRegistry,
+  StartSessionTelemetry,
+  StartSessionTelemetryOptions,
+  StartupRecoveryState,
+  TelemetryLogger,
+  TelemetryMeter,
+  TelemetryTracer,
+  ToolCallState,
+  TurnSequenceRegistry,
+} from "./handler-types.ts";
+
+export function registerHandlers(pi: unknown, options: RegisterHandlersOptions = {}): void {
+  const api = resolveObservMePiApi(pi);
+  const state: HandlerSessionState = {};
+  const errorRecorder = createStatefulHandlerErrorRecorder(state, options.onHandlerError);
+  const registrar = new HandlerRegistrar(api, state, errorRecorder);
+  const lifecycleQueue = new SerializedLifecycleQueue();
+
+  setDefaultHandlerErrorRecorder(errorRecorder);
+  registerLifecycleHandlers(registrar, state, options, lifecycleQueue);
+  registerAgentTurnHandlers(registrar, state);
+  registerLlmHandlers(registrar, state);
+  registerToolBashHandlers(registrar, state);
+  registerSessionEventHandlers(registrar, state);
+  registrar.commit();
+}