@senad-d/observme 0.1.3 → 0.1.5

package/src/pi/handler-runtime.ts

@@ -1,16 +1,17 @@
 import { randomUUID } from "node:crypto";
 import { performance } from "node:perf_hooks";
 import type { Histogram, Span } from "@opentelemetry/api";
-import { trace } from "@opentelemetry/api";
 import type { ObservMeConfig } from "../config/schema.ts";
-import { ObservMeLogSdk } from "../otel/logs.ts";
-import { ObservMeMetricSdk } from "../otel/metrics.ts";
-import { startOtelSdk } from "../otel/sdk.ts";
-import { ObservMeTraceSdk } from "../otel/traces.ts";
+import { createLogSessionScopedOtelSdk, type ObservMeLogSdk } from "../otel/logs.ts";
+import { createMetricSessionScopedOtelSdk, type ObservMeMetricSdk } from "../otel/metrics.ts";
+import { startOtelSdk, toOtelStartupError, type SessionScopedOtelSdk } from "../otel/sdk.ts";
+import { runBoundedOtelOperation } from "../otel/shutdown.ts";
+import { createTraceSessionScopedOtelSdk, type ObservMeTraceSdk } from "../otel/traces.ts";
 import { inheritTenantSaltEnvironment } from "../privacy/hash.ts";
 import { LOG_ATTRIBUTES, RESOURCE_ATTRIBUTES } from "../semconv/attributes.ts";
 import {
   LOG_EVENT_NAMES,
+  OBSERVME_AGENT_LEASE_METRIC_OPTIONS,
   OBSERVME_COUNTER_METRIC_NAMES,
   OBSERVME_GAUGE_METRIC_NAMES,
   OBSERVME_HISTOGRAM_METRIC_NAMES,
@@ -18,6 +19,7 @@ import {
   OFFICIAL_GENAI_METRIC_NAMES,
 } from "../semconv/metrics.ts";
 import { BoundedMap, type BoundedMapEviction } from "../util/bounded-map.ts";
+import { createActiveAgentLease } from "./active-agent-lease.ts";
 import type { AgentLineageContext } from "./agent-lineage.ts";
 import { buildResourceLineageAttributes } from "./agent-lineage.ts";
 import type { AgentTreeNode } from "./agent-tree-tracker.ts";
@@ -30,6 +32,7 @@ import {
   evictToolCallState,
   evictWaitJoinState,
   isRecord,
+  metricLabels,
   normalizeMetricValue,
   readBoolean,
   readString,
@@ -46,9 +49,12 @@ import type {
   HandlerRegistration,
   HandlerSessionState,
   ObservMeHandlerContext,
+  PiEventName,
+  PiHandler,
   ObservMeMetrics,
   ObservMePiApi,
   ObservMeTelemetrySession,
+  RuntimeHandler,
   SpanRegistry,
   StartSessionTelemetryOptions,
   TelemetryMeter,
@@ -63,6 +69,7 @@ const piApiCompatibilityErrorMessage =
   "ObservMe/Pi API compatibility error: expected Pi ExtensionAPI with on(eventName, handler) before registering ObservMe handlers.";
 const eventRegistrationOrder = [
   "session_start",
+  "session_info_changed",
   "agent_start",
   "turn_start",
   "before_provider_request",
@@ -73,18 +80,15 @@ const eventRegistrationOrder = [
   "tool_result",
   "tool_execution_end",
   "user_bash",
-  "bashExecution",
   "model_select",
-  "model_change",
   "thinking_level_select",
-  "thinking_level_change",
   "session_before_tree",
   "session_tree",
   "session_compact",
   "turn_end",
   "agent_end",
   "session_shutdown",
-] as const;
+] as const satisfies readonly PiEventName[];
 const eventRegistrationIndexes = createEventRegistrationIndexes();
 
 let defaultHandlerErrorRecorder: HandlerErrorRecorder = recordInternalErrorFallback;
@@ -101,8 +105,8 @@ export class HandlerRegistrar {
     this.#errorRecorder = errorRecorder;
   }
 
-  add(eventName: string, handler: Handler): void {
-    this.#registrations.push({ eventName, handler });
+  add<Name extends PiEventName>(eventName: Name, handler: PiHandler<Name>): void {
+    this.#registrations.push({ eventName, handler: handler as unknown as RuntimeHandler });
   }
 
   commit(): void {
@@ -122,11 +126,12 @@ export class HandlerRegistrar {
 export class SerializedLifecycleQueue {
   #previous = Promise.resolve();
 
-  wrap(fn: Handler): Handler {
-    return runSerializedLifecycleHandler.bind(undefined, this, fn);
+  wrap<Name extends PiEventName>(fn: PiHandler<Name>): PiHandler<Name> {
+    const runtimeHandler = fn as unknown as RuntimeHandler;
+    return runSerializedLifecycleHandler.bind(undefined, this, runtimeHandler) as PiHandler<Name>;
   }
 
-  run(fn: Handler, event: unknown, ctx: ObservMeHandlerContext): Promise<void> {
+  run(fn: RuntimeHandler, event: unknown, ctx: Parameters<RuntimeHandler>[1]): Promise<void> {
     // Pi docs guarantee /new, /resume, and /fork emit session_shutdown before session_start;
     // ctx.reload() emits session_shutdown then session_start while the old command call frame can
     // continue. ObservMe queues both lifecycle handlers together so async startup, shutdown,
@@ -143,19 +148,30 @@ export function resolveObservMePiApi(pi: unknown): ObservMePiApi {
   const on = pi.on;
   if (typeof on !== "function") throw new TypeError(piApiCompatibilityErrorMessage);
 
-  return { on: callPiOn.bind(undefined, pi, on as ObservMePiApi["on"]) };
+  const appendEntry = typeof pi.appendEntry === "function"
+    ? (pi.appendEntry.bind(pi) as NonNullable<ObservMePiApi["appendEntry"]>)
+    : undefined;
+  const getThinkingLevel = typeof pi.getThinkingLevel === "function"
+    ? (pi.getThinkingLevel.bind(pi) as NonNullable<ObservMePiApi["getThinkingLevel"]>)
+    : undefined;
+
+  return {
+    on: on.bind(pi) as ObservMePiApi["on"],
+    appendEntry,
+    getThinkingLevel,
+  };
 }
 
 export function setDefaultHandlerErrorRecorder(recorder: HandlerErrorRecorder): void {
   defaultHandlerErrorRecorder = recorder;
 }
 
-export function safeHandler(
+export function safeHandler<Event = unknown, Context = ObservMeHandlerContext>(
   name: string,
-  fn: Handler,
+  fn: Handler<Event, Context>,
   recorder: HandlerErrorRecorder = defaultHandlerErrorRecorder,
-): Handler {
-  return runSafeHandler.bind(undefined, name, fn, recorder);
+): Handler<Event, Context> {
+  return (runSafeHandler<Event, Context>).bind(undefined, name, fn, recorder);
 }
 
 export function createStatefulHandlerErrorRecorder(
@@ -166,20 +182,37 @@ export function createStatefulHandlerErrorRecorder(
 }
 
 export async function startSessionTelemetry(options: StartSessionTelemetryOptions): Promise<ObservMeTelemetrySession> {
+  if (!options.config.enabled) throw new Error("ObservMe telemetry cannot start while ObservMe is disabled.");
+
   const config = withTelemetrySessionResourceAttributes(options.config, options.lineage);
-  const traceSdk = new ObservMeTraceSdk({ config });
-  const metricSdk = new ObservMeMetricSdk({ config });
-  const logSdk = new ObservMeLogSdk({ config });
-  const signalSdk = createCompositeOtelSignalSdk(traceSdk, metricSdk, logSdk);
+  const traceSdk = createTraceSessionScopedOtelSdk({ config, agent: options.lineage });
+  const metricSdk = createMetricSessionScopedOtelSdk({ config, agent: options.lineage });
+  const logSdk = createLogSessionScopedOtelSdk({ config, agent: options.lineage });
+  const signalSdk = createCompositeOtelSignalSdk(
+    traceSdk,
+    metricSdk,
+    logSdk,
+    config.shutdown.flushTimeoutMs,
+  );
   const controller = await startOtelSdk({
     config,
     agent: options.lineage,
     sdkFactory: returnCompositeSignalSdk.bind(undefined, signalSdk),
   });
-  const tracer = traceSdk.tracer ?? trace.getTracer("@senad-d/observme");
+  const tracer = traceSdk.tracer;
   const metrics = createObservMeMetrics(metricSdk.meter);
   const sessionReference: HandlerSessionState = {};
   const getTelemetryDropTarget = resolveSessionTelemetryDropTarget.bind(undefined, sessionReference, metrics);
+  const spans = createSpanRegistry(config, metrics, getTelemetryDropTarget);
+  const agentTree = createAgentTreeTracker(config, options.lineage, metrics, getTelemetryDropTarget);
+  const turnSequences = createTurnSequenceRegistry(config, metrics, getTelemetryDropTarget);
+  const activeAgentLease = createActiveAgentLease({
+    instrument: metrics.agentLeaseExpiresUnixTimeSeconds,
+    leaseDurationMillis: config.metrics.activeAgentLeaseDurationMillis,
+    attributes: metricLabels(config, options.lineage),
+    wallClockNow: options.wallClockNow,
+    enabled: config.metrics.enabled,
+  });
   const session: ObservMeTelemetrySession = {
     config,
     lineage: options.lineage,
@@ -188,14 +221,15 @@ export async function startSessionTelemetry(options: StartSessionTelemetryOption
     meter: metricSdk.meter,
     logger: logSdk.logger,
     metrics,
-    spans: createSpanRegistry(config, metrics, getTelemetryDropTarget),
-    agentTree: createAgentTreeTracker(config, options.lineage, metrics, getTelemetryDropTarget),
+    spans,
+    activeAgentLease,
+    agentTree,
     now: options.now ?? monotonicNowMs,
     activeAgentRecorded: false,
     agentRunSequence: 0,
     llmRequestSequence: 0,
     toolCallSequence: 0,
-    turnSequences: createTurnSequenceRegistry(config, metrics, getTelemetryDropTarget),
+    turnSequences,
   };
 
   sessionReference.session = session;
@@ -206,8 +240,9 @@ export function createCompositeOtelSignalSdk(
   traceSdk: ObservMeTraceSdk,
   metricSdk: ObservMeMetricSdk,
   logSdk: ObservMeLogSdk,
+  cleanupTimeoutMs = 3_000,
 ): CompositeOtelSignalSdk {
-  return new ObservMeCompositeOtelSignalSdk(traceSdk, metricSdk, logSdk);
+  return new ObservMeCompositeOtelSignalSdk(traceSdk, metricSdk, logSdk, cleanupTimeoutMs);
 }
 
 export function createObservMeMetrics(meter: TelemetryMeter): ObservMeMetrics {
@@ -252,6 +287,10 @@ export function createObservMeMetrics(meter: TelemetryMeter): ObservMeMetrics {
     eventsObserved: meter.createCounter(OBSERVME_COUNTER_METRIC_NAMES.EVENTS_OBSERVED_TOTAL),
     activeSpans: meter.createUpDownCounter(OBSERVME_GAUGE_METRIC_NAMES.ACTIVE_SPANS),
     activeAgents: meter.createUpDownCounter(OBSERVME_GAUGE_METRIC_NAMES.ACTIVE_AGENTS),
+    agentLeaseExpiresUnixTimeSeconds: meter.createObservableGauge(
+      OBSERVME_GAUGE_METRIC_NAMES.AGENT_LEASE_EXPIRES_UNIXTIME_SECONDS,
+      OBSERVME_AGENT_LEASE_METRIC_OPTIONS,
+    ),
     workflowDurationMs: createHistogram(meter, OBSERVME_HISTOGRAM_METRIC_NAMES.WORKFLOW_DURATION_MS),
     agentRunDurationMs: createHistogram(meter, OBSERVME_HISTOGRAM_METRIC_NAMES.AGENT_RUN_DURATION_MS),
     agentLifetimeDurationMs: createHistogram(meter, OBSERVME_HISTOGRAM_METRIC_NAMES.AGENT_LIFETIME_DURATION_MS),
@@ -378,8 +417,8 @@ export function buildTelemetryInstanceResourceAttributes(instanceId: string): Re
   };
 }
 
-function createEventRegistrationIndexes(): Map<string, number> {
-  const indexes = new Map<string, number>();
+function createEventRegistrationIndexes(): Map<PiEventName, number> {
+  const indexes = new Map<PiEventName, number>();
   for (const [index, name] of eventRegistrationOrder.entries()) indexes.set(name, index);
   return indexes;
 }
@@ -392,30 +431,30 @@ function compareHandlerRegistrations(left: HandlerRegistration, right: HandlerRe
   return registrationIndex(left.eventName) - registrationIndex(right.eventName);
 }
 
-function registrationIndex(eventName: string): number {
+function registrationIndex(eventName: PiEventName): number {
   return eventRegistrationIndexes.get(eventName) ?? eventRegistrationOrder.length;
 }
 
 function registerObservedHandler(
   api: ObservMePiApi,
-  name: string,
-  handler: Handler,
+  name: PiEventName,
+  handler: RuntimeHandler,
   state: HandlerSessionState,
   errorRecorder: HandlerErrorRecorder,
 ): void {
   api.on(name, safeHandler(name, observeHandler(name, handler, state), errorRecorder));
 }
 
-function observeHandler(name: string, fn: Handler, state: HandlerSessionState): Handler {
+function observeHandler(name: string, fn: RuntimeHandler, state: HandlerSessionState): RuntimeHandler {
   return runObservedHandler.bind(undefined, name, fn, state);
 }
 
 async function runObservedHandler(
   name: string,
-  fn: Handler,
+  fn: RuntimeHandler,
   state: HandlerSessionState,
   event: unknown,
-  ctx: ObservMeHandlerContext,
+  ctx: Parameters<RuntimeHandler>[1],
 ): Promise<void> {
   const startedAtMs = Date.now();
   const sessionBefore = state.session;
@@ -453,12 +492,12 @@ function recordHandlerObservation(
   session.metrics.handlerDurationMs.record(Math.max(0, Date.now() - startedAtMs), { operation, status });
 }
 
-async function runSafeHandler(
+async function runSafeHandler<Event, Context>(
   name: string,
-  fn: Handler,
+  fn: Handler<Event, Context>,
   recorder: HandlerErrorRecorder,
-  event: unknown,
-  ctx: ObservMeHandlerContext,
+  event: Event,
+  ctx: Context,
 ): Promise<void> {
   try {
     await fn(event, ctx);
@@ -469,14 +508,18 @@ async function runSafeHandler(
 
 async function runSerializedLifecycleHandler(
   queue: SerializedLifecycleQueue,
-  fn: Handler,
+  fn: RuntimeHandler,
   event: unknown,
-  ctx: ObservMeHandlerContext,
+  ctx: Parameters<RuntimeHandler>[1],
 ): Promise<void> {
   await queue.run(fn, event, ctx);
 }
 
-async function invokeHandler(fn: Handler, event: unknown, ctx: ObservMeHandlerContext): Promise<void> {
+async function invokeHandler(
+  fn: RuntimeHandler,
+  event: unknown,
+  ctx: Parameters<RuntimeHandler>[1],
+): Promise<void> {
   await fn(event, ctx);
 }
 
@@ -484,10 +527,6 @@ function ignoreLifecycleQueueError(): undefined {
   return undefined;
 }
 
-function callPiOn(pi: Record<string, unknown>, on: ObservMePiApi["on"], eventName: string, handler: Handler): void {
-  on.call(pi, eventName, handler);
-}
-
 function returnCompositeSignalSdk(signalSdk: CompositeOtelSignalSdk): CompositeOtelSignalSdk {
   return signalSdk;
 }
@@ -610,17 +649,46 @@ class ObservMeCompositeOtelSignalSdk implements CompositeOtelSignalSdk {
   readonly traceSdk: ObservMeTraceSdk;
   readonly metricSdk: ObservMeMetricSdk;
   readonly logSdk: ObservMeLogSdk;
-
-  constructor(traceSdk: ObservMeTraceSdk, metricSdk: ObservMeMetricSdk, logSdk: ObservMeLogSdk) {
+  readonly #cleanupTimeoutMs: number;
+  readonly #startedSignalSdks: SessionScopedOtelSdk[] = [];
+  #startingSignalSdk?: SessionScopedOtelSdk;
+  #state: CompositeOtelSignalSdk["state"] = "idle";
+
+  constructor(
+    traceSdk: ObservMeTraceSdk,
+    metricSdk: ObservMeMetricSdk,
+    logSdk: ObservMeLogSdk,
+    cleanupTimeoutMs: number,
+  ) {
     this.traceSdk = traceSdk;
     this.metricSdk = metricSdk;
     this.logSdk = logSdk;
+    this.#cleanupTimeoutMs = cleanupTimeoutMs;
   }
 
-  start(): void {
-    this.traceSdk.start();
-    this.metricSdk.start();
-    this.logSdk.start();
+  get state(): CompositeOtelSignalSdk["state"] {
+    return this.#state;
+  }
+
+  async start(): Promise<void> {
+    if (this.#state === "started") return;
+    if (this.#state !== "idle") throw new Error(`ObservMe OTEL signal SDK cannot start from ${this.#state}.`);
+
+    this.#state = "starting";
+    try {
+      await this.startSignalSdk(this.traceSdk);
+      await this.startSignalSdk(this.metricSdk);
+      await this.startSignalSdk(this.logSdk);
+      this.#state = "started";
+    } catch (error) {
+      const cleanup = await runBoundedOtelOperation(
+        "shutdown",
+        this.shutdownStartedSignalSdks.bind(this),
+        this.#cleanupTimeoutMs,
+      );
+      this.#state = "failed";
+      throw toOtelStartupError(error, cleanup);
+    }
   }
 
   async forceFlush(): Promise<void> {
@@ -628,6 +696,43 @@ class ObservMeCompositeOtelSignalSdk implements CompositeOtelSignalSdk {
   }
 
   async shutdown(): Promise<void> {
-    await Promise.all([this.traceSdk.shutdown(), this.metricSdk.shutdown(), this.logSdk.shutdown()]);
+    if (this.#state === "shutdown") return;
+
+    try {
+      await this.shutdownStartedSignalSdks();
+    } finally {
+      this.#state = "shutdown";
+    }
+  }
+
+  private async startSignalSdk(sdk: SessionScopedOtelSdk): Promise<void> {
+    this.#startingSignalSdk = sdk;
+    await sdk.start?.();
+    this.#startedSignalSdks.push(sdk);
+    this.#startingSignalSdk = undefined;
   }
+
+  private async shutdownStartedSignalSdks(): Promise<void> {
+    const signalSdks = this.takeStartedSignalSdks();
+    const results = await Promise.allSettled(signalSdks.map(shutdownCompositeSignalSdk));
+
+    for (const result of results) {
+      if (result.status === "rejected") throw result.reason;
+    }
+  }
+
+  private takeStartedSignalSdks(): SessionScopedOtelSdk[] {
+    const signalSdks = [...this.#startedSignalSdks];
+    if (this.#startingSignalSdk && !signalSdks.includes(this.#startingSignalSdk)) {
+      signalSdks.push(this.#startingSignalSdk);
+    }
+
+    this.#startedSignalSdks.length = 0;
+    this.#startingSignalSdk = undefined;
+    return signalSdks.reverse();
+  }
+}
+
+async function shutdownCompositeSignalSdk(sdk: SessionScopedOtelSdk): Promise<void> {
+  await sdk.shutdown?.();
 }

package/src/pi/handler-types.ts

@@ -1,5 +1,10 @@
-import type { Counter, Histogram, Meter, Span, Tracer, UpDownCounter } from "@opentelemetry/api";
+import type { Counter, Histogram, Meter, ObservableGauge, Span, Tracer, UpDownCounter } from "@opentelemetry/api";
 import type { Logger } from "@opentelemetry/api-logs";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionEvent,
+} from "@earendil-works/pi-coding-agent";
 import type { EnsureProjectConfig as BootstrapEnsureProjectConfig } from "../config/bootstrap-project-config.ts";
 import type {
   LoadSessionConfigOptions,
@@ -13,6 +18,7 @@ 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 { ActiveAgentLeaseController } from "./active-agent-lease.ts";
 import type { AgentTreeTracker } from "./agent-tree-tracker.ts";
 import type {
   AgentWaitJoinState,
@@ -22,11 +28,24 @@ import type {
 
 export type AttributePrimitive = boolean | number | string | string[];
 export type AttributeMap = Record<string, AttributePrimitive>;
-export type TelemetryMeter = Pick<Meter, "createCounter" | "createHistogram" | "createUpDownCounter">;
+export type TelemetryMeter = Pick<
+  Meter,
+  "createCounter" | "createHistogram" | "createObservableGauge" | "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 PiEventName = ExtensionEvent["type"];
+export type PiEvent<Name extends PiEventName> = Extract<ExtensionEvent, { type: Name }>;
+export type Handler<Event = unknown, Context = ObservMeHandlerContext> = (
+  event: Event,
+  ctx: Context,
+) => Promise<void> | void;
+export type PiHandler<Name extends PiEventName> = Handler<PiEvent<Name>, ExtensionContext>;
+export type RuntimeHandler = Handler<unknown, ExtensionContext>;
 export type HandlerErrorRecorder = (name: string, error: unknown) => void;
+export type AppendEntry = ExtensionAPI["appendEntry"];
+export type GetThinkingLevel = ExtensionAPI["getThinkingLevel"];
+export type ObservMeSessionManager = ExtensionContext["sessionManager"];
 export type LoadSessionConfig = (
   options: LoadSessionConfigOptions,
 ) => Promise<ObservMeConfig | LoadSessionConfigResult>;
@@ -52,7 +71,6 @@ export interface SessionRecoveryHeader {
   readonly timestamp?: string;
   readonly cwd?: string;
   readonly parentSession?: string;
-  readonly correlation?: MinimalSessionCorrelation;
 }
 
 export interface StartupRecoveryState {
@@ -63,24 +81,21 @@ export interface StartupRecoveryState {
 }
 
 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 cwd?: ExtensionContext["cwd"];
+  readonly hasUI?: ExtensionContext["hasUI"];
+  readonly sessionManager?: ObservMeSessionManager;
+  readonly model?: Exclude<ExtensionContext["model"], undefined>;
   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;
+  on: <Name extends PiEventName>(eventName: Name, handler: PiHandler<Name>) => void;
+  appendEntry?: AppendEntry;
+  getThinkingLevel?: GetThinkingLevel;
 }
 
 export interface RegisterHandlersOptions {
@@ -88,18 +103,22 @@ export interface RegisterHandlersOptions {
   readonly startTelemetry?: StartSessionTelemetry;
   readonly env?: NodeJS.ProcessEnv;
   readonly now?: () => number;
+  readonly wallClockNow?: () => number;
   readonly configDirName?: string;
   readonly trustedParentContext?: boolean;
   readonly requireCompleteParentEnvelope?: boolean;
   readonly readSessionHeader?: ReadSessionHeader;
   readonly ensureProjectConfig?: EnsureProjectConfig;
   readonly onHandlerError?: HandlerErrorRecorder;
+  readonly appendEntry?: AppendEntry;
+  readonly getThinkingLevel?: GetThinkingLevel;
 }
 
 export interface StartSessionTelemetryOptions {
   readonly config: ObservMeConfig;
   readonly lineage: AgentLineageContext;
   readonly now?: () => number;
+  readonly wallClockNow?: () => number;
 }
 
 export interface TurnSequenceRegistry {
@@ -119,6 +138,7 @@ export interface ObservMeTelemetrySession {
   readonly logger: TelemetryLogger;
   readonly metrics: ObservMeMetrics;
   readonly spans: SpanRegistry;
+  readonly activeAgentLease?: ActiveAgentLeaseController;
   agentTree: AgentTreeTracker;
   sessionSpan?: Span;
   sessionAttributes?: AttributeMap;
@@ -179,6 +199,7 @@ export interface ObservMeMetrics {
   readonly eventsObserved: Counter;
   readonly activeSpans: UpDownCounter;
   readonly activeAgents: UpDownCounter;
+  readonly agentLeaseExpiresUnixTimeSeconds: ObservableGauge;
   readonly workflowDurationMs: Histogram;
   readonly agentRunDurationMs: Histogram;
   readonly agentLifetimeDurationMs: Histogram;
@@ -241,18 +262,20 @@ export interface CompositeOtelSignalSdk {
   readonly traceSdk: ObservMeTraceSdk;
   readonly metricSdk: ObservMeMetricSdk;
   readonly logSdk: ObservMeLogSdk;
-  start: () => void;
+  readonly state: "idle" | "starting" | "started" | "failed" | "shutdown";
+  start: () => Promise<void>;
   forceFlush: () => Promise<void>;
   shutdown: () => Promise<void>;
 }
 
 export interface HandlerSessionState {
   session?: ObservMeTelemetrySession;
+  pendingCleanup?: ObservMeTelemetrySession;
 }
 
 export interface HandlerRegistration {
-  readonly eventName: string;
-  readonly handler: Handler;
+  readonly eventName: PiEventName;
+  readonly handler: RuntimeHandler;
 }
 
 export interface SessionConfigLoadResult {

package/src/pi/handlers.ts

@@ -31,11 +31,13 @@ export {
   workflowFailed,
 } from "./handler-runtime.ts";
 export type {
+  AppendEntry,
   AttributeMap,
   AttributePrimitive,
   BranchPreparationState,
   CompositeOtelSignalSdk,
   EnsureProjectConfig,
+  GetThinkingLevel,
   Handler,
   HandlerErrorRecorder,
   LoadSessionConfig,
@@ -43,8 +45,12 @@ export type {
   ObservMeHandlerContext,
   ObservMeMetrics,
   ObservMePiApi,
+  ObservMeSessionManager,
   ObservMeTelemetrySession,
   PendingBashOperationState,
+  PiEvent,
+  PiEventName,
+  PiHandler,
   ReadSessionHeader,
   RegisterHandlersOptions,
   SessionRecoveryHeader,
@@ -65,9 +71,14 @@ export function registerHandlers(pi: unknown, options: RegisterHandlersOptions =
   const errorRecorder = createStatefulHandlerErrorRecorder(state, options.onHandlerError);
   const registrar = new HandlerRegistrar(api, state, errorRecorder);
   const lifecycleQueue = new SerializedLifecycleQueue();
+  const runtimeOptions = {
+    ...options,
+    appendEntry: options.appendEntry ?? api.appendEntry,
+    getThinkingLevel: options.getThinkingLevel ?? api.getThinkingLevel,
+  };
 
   setDefaultHandlerErrorRecorder(errorRecorder);
-  registerLifecycleHandlers(registrar, state, options, lifecycleQueue);
+  registerLifecycleHandlers(registrar, state, runtimeOptions, lifecycleQueue);
   registerAgentTurnHandlers(registrar, state);
   registerLlmHandlers(registrar, state);
   registerToolBashHandlers(registrar, state);