@senad-d/observme 0.1.2 → 0.1.4

package/src/pi/handler-types.ts

@@ -1,4 +1,4 @@
-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 { EnsureProjectConfig as BootstrapEnsureProjectConfig } from "../config/bootstrap-project-config.ts";
 import type {
@@ -13,6 +13,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,7 +23,10 @@ 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;
@@ -88,6 +92,7 @@ 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;
@@ -100,6 +105,7 @@ export interface StartSessionTelemetryOptions {
   readonly config: ObservMeConfig;
   readonly lineage: AgentLineageContext;
   readonly now?: () => number;
+  readonly wallClockNow?: () => number;
 }
 
 export interface TurnSequenceRegistry {
@@ -119,6 +125,7 @@ export interface ObservMeTelemetrySession {
   readonly logger: TelemetryLogger;
   readonly metrics: ObservMeMetrics;
   readonly spans: SpanRegistry;
+  readonly activeAgentLease?: ActiveAgentLeaseController;
   agentTree: AgentTreeTracker;
   sessionSpan?: Span;
   sessionAttributes?: AttributeMap;
@@ -179,6 +186,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;

package/src/pi/integration-api.ts

@@ -33,12 +33,22 @@ interface IntegrationPiApi {
   readonly events?: IntegrationEventBus;
 }
 
+const integrationIdentifierPattern = /^[A-Za-z0-9._:-]{1,128}$/u;
+const maximumIntegrationCommandLength = 4096;
+const maximumIntegrationArgumentCount = 256;
+const maximumIntegrationArgumentLength = 4096;
+const maximumIntegrationEnvironmentEntries = 4096;
+
 export function registerObservMeIntegration(pi: unknown, state: HandlerSessionState): (() => void) | undefined {
   const events = resolveIntegrationEventBus(pi);
   if (!events) return undefined;
 
   const api = new SessionBackedObservMeIntegrationApi(state);
-  return events.on(OBSERVME_INTEGRATION_CHANNEL, api.handleRequest.bind(api));
+  try {
+    return events.on(OBSERVME_INTEGRATION_CHANNEL, api.handleRequest.bind(api));
+  } catch {
+    return undefined;
+  }
 }
 
 export class SessionBackedObservMeIntegrationApi implements ObservMeIntegrationApi {
@@ -50,8 +60,8 @@ export class SessionBackedObservMeIntegrationApi implements ObservMeIntegrationA
   }
 
   handleRequest(value: unknown): void {
-    if (!isCompatibleIntegrationRequest(value)) return;
     try {
+      if (!isCompatibleIntegrationRequest(value)) return;
       value.respond(this);
     } catch {
       return;
@@ -82,8 +92,12 @@ export class SessionBackedObservMeIntegrationApi implements ObservMeIntegrationA
   startSubagent(options: ObservMeStartSubagentOptions = {}): ObservMeStartedSubagent | ObservMeIntegrationFailure {
     const session = this.#state.session;
     if (!session) return integrationFailure("session_unavailable");
-
     try {
+      if (!isValidStartSubagentOptions(options)) return integrationFailure("invalid_request");
+      if (options.spawnId && session.spans.activeSubagentSpawns.has(options.spawnId)) {
+        return integrationFailure("spawn_already_exists");
+      }
+
       const started = startSubagentSpawn(session, options);
       return {
         ok: true,
@@ -103,9 +117,12 @@ export class SessionBackedObservMeIntegrationApi implements ObservMeIntegrationA
   ): ObservMeIntegrationSuccess | ObservMeIntegrationFailure {
     const session = this.#state.session;
     if (!session) return integrationFailure("session_unavailable");
-    if (!session.spans.activeSubagentSpawns.get(spawnId)) return integrationFailure("spawn_not_found");
-
     try {
+      if (!isValidIntegrationIdentifier(spawnId) || !isValidCompleteSubagentOptions(options)) {
+        return integrationFailure("invalid_request");
+      }
+      if (!session.spans.activeSubagentSpawns.has(spawnId)) return integrationFailure("spawn_not_found");
+
       completeSubagentSpawn(session, spawnId, options);
       return integrationSuccess();
     } catch {
@@ -119,9 +136,12 @@ export class SessionBackedObservMeIntegrationApi implements ObservMeIntegrationA
   ): ObservMeIntegrationSuccess | ObservMeIntegrationFailure {
     const session = this.#state.session;
     if (!session) return integrationFailure("session_unavailable");
-    if (!session.spans.activeSubagentSpawns.get(spawnId)) return integrationFailure("spawn_not_found");
-
     try {
+      if (!isValidIntegrationIdentifier(spawnId) || !isValidFailSubagentOptions(options)) {
+        return integrationFailure("invalid_request");
+      }
+      if (!session.spans.activeSubagentSpawns.has(spawnId)) return integrationFailure("spawn_not_found");
+
       failSubagentSpawn(session, spawnId, options);
       return integrationSuccess();
     } catch {
@@ -157,8 +177,15 @@ export class SessionBackedObservMeIntegrationApi implements ObservMeIntegrationA
   ): ObservMeStartedWaitJoin | ObservMeIntegrationFailure {
     const session = this.#state.session;
     if (!session) return integrationFailure("session_unavailable");
-
     try {
+      if (!isValidWaitJoinOptions(options)) return integrationFailure("invalid_request");
+
+      const requestedId = resolveRequestedWaitJoinId(options, kind);
+      const registry = kind === "wait" ? session.spans.activeAgentWaits : session.spans.activeAgentJoins;
+      if (requestedId && registry.has(requestedId)) {
+        return integrationFailure(kind === "wait" ? "wait_already_exists" : "join_already_exists");
+      }
+
       const started = kind === "wait" ? startAgentWait(session, options) : startAgentJoin(session, options);
       return { ok: true, id: started.id };
     } catch {
@@ -173,10 +200,13 @@ export class SessionBackedObservMeIntegrationApi implements ObservMeIntegrationA
   ): ObservMeIntegrationSuccess | ObservMeIntegrationFailure {
     const session = this.#state.session;
     if (!session) return integrationFailure("session_unavailable");
-    const registry = kind === "wait" ? session.spans.activeAgentWaits : session.spans.activeAgentJoins;
-    if (!registry.get(id)) return integrationFailure(kind === "wait" ? "wait_not_found" : "join_not_found");
-
     try {
+      if (!isValidIntegrationIdentifier(id) || !isValidWaitJoinOptions(options)) {
+        return integrationFailure("invalid_request");
+      }
+      const registry = kind === "wait" ? session.spans.activeAgentWaits : session.spans.activeAgentJoins;
+      if (!registry.has(id)) return integrationFailure(kind === "wait" ? "wait_not_found" : "join_not_found");
+
       if (kind === "wait") endAgentWait(session, id, options);
       else endAgentJoin(session, id, options);
       return integrationSuccess();
@@ -188,8 +218,12 @@ export class SessionBackedObservMeIntegrationApi implements ObservMeIntegrationA
 
 function resolveIntegrationEventBus(pi: unknown): IntegrationEventBus | undefined {
   if (!pi || typeof pi !== "object") return undefined;
-  const events = (pi as IntegrationPiApi).events;
-  return events && typeof events.on === "function" ? events : undefined;
+  try {
+    const events = (pi as IntegrationPiApi).events;
+    return events && typeof events.on === "function" ? events : undefined;
+  } catch {
+    return undefined;
+  }
 }
 
 function isCompatibleIntegrationRequest(value: unknown): value is ObservMeIntegrationRequest {
@@ -202,6 +236,143 @@ function isCompatibleIntegrationRequest(value: unknown): value is ObservMeIntegr
   );
 }
 
+function isValidStartSubagentOptions(value: unknown): value is ObservMeStartSubagentOptions {
+  if (!isIntegrationRecord(value)) return false;
+  const options = value as Partial<ObservMeStartSubagentOptions>;
+  return (
+    isOptionalIntegrationIdentifier(options.spawnId) &&
+    isOptionalIntegrationIdentifier(options.childAgentId) &&
+    isOptionalBoundedString(options.command, maximumIntegrationCommandLength) &&
+    isValidIntegrationArguments(options.args) &&
+    isOptionalSpawnType(options.spawnType) &&
+    isOptionalSpawnReason(options.spawnReason) &&
+    isOptionalIntegrationIdentifier(options.toolCallId) &&
+    isValidIntegrationEnvironment(options.env)
+  );
+}
+
+function isValidCompleteSubagentOptions(value: unknown): value is ObservMeCompleteSubagentOptions {
+  if (!isIntegrationRecord(value)) return false;
+  const options = value as Partial<ObservMeCompleteSubagentOptions>;
+  return (
+    isOptionalIntegrationIdentifier(options.childAgentId) &&
+    isOptionalChildStatus(options.childStatus) &&
+    (options.outcome === undefined || options.outcome === "completed" || options.outcome === "failed" || options.outcome === "cancelled")
+  );
+}
+
+function isValidFailSubagentOptions(value: unknown): value is ObservMeFailSubagentOptions {
+  if (!isIntegrationRecord(value)) return false;
+  const options = value as Partial<ObservMeFailSubagentOptions>;
+  return isOptionalIntegrationIdentifier(options.childAgentId) && isOptionalBoundedString(options.errorClass, 256);
+}
+
+function isValidWaitJoinOptions(value: unknown): value is ObservMeWaitJoinOptions {
+  if (!isIntegrationRecord(value)) return false;
+  const options = value as Partial<ObservMeWaitJoinOptions>;
+  return (
+    isOptionalIntegrationIdentifier(options.id) &&
+    isOptionalIntegrationIdentifier(options.spawnId) &&
+    isOptionalIntegrationIdentifier(options.childAgentId) &&
+    isOptionalChildStatus(options.childStatus) &&
+    isOptionalJoinStatus(options.joinStatus) &&
+    isOptionalWaitReason(options.reason) &&
+    (options.failurePropagated === undefined || typeof options.failurePropagated === "boolean") &&
+    (options.durationMs === undefined || isValidDuration(options.durationMs))
+  );
+}
+
+function isIntegrationRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isValidIntegrationIdentifier(value: unknown): value is string {
+  return typeof value === "string" && integrationIdentifierPattern.test(value);
+}
+
+function isOptionalIntegrationIdentifier(value: unknown): value is string | undefined {
+  return value === undefined || isValidIntegrationIdentifier(value);
+}
+
+function isOptionalBoundedString(value: unknown, maximumLength: number): value is string | undefined {
+  return value === undefined || (typeof value === "string" && value.length <= maximumLength);
+}
+
+function isValidIntegrationArguments(value: unknown): value is readonly string[] | undefined {
+  return (
+    value === undefined ||
+    (Array.isArray(value) &&
+      value.length <= maximumIntegrationArgumentCount &&
+      value.every(isValidIntegrationArgument))
+  );
+}
+
+function isValidIntegrationArgument(value: unknown): value is string {
+  return typeof value === "string" && value.length <= maximumIntegrationArgumentLength;
+}
+
+function isValidIntegrationEnvironment(value: unknown): boolean {
+  if (value === undefined) return true;
+  if (!isIntegrationRecord(value)) return false;
+  const entries = Object.entries(value);
+  return entries.length <= maximumIntegrationEnvironmentEntries && entries.every(isValidIntegrationEnvironmentEntry);
+}
+
+function isValidIntegrationEnvironmentEntry(entry: [string, unknown]): boolean {
+  return entry[0].length > 0 && (typeof entry[1] === "string" || entry[1] === undefined);
+}
+
+function isOptionalSpawnType(value: unknown): boolean {
+  return value === undefined || value === "command" || value === "tool" || value === "extension" || value === "unknown";
+}
+
+function isOptionalSpawnReason(value: unknown): boolean {
+  return (
+    value === undefined ||
+    value === "delegated_task" ||
+    value === "parallel_search" ||
+    value === "review" ||
+    value === "tool_wrapper" ||
+    value === "unknown"
+  );
+}
+
+function isOptionalChildStatus(value: unknown): boolean {
+  return (
+    value === undefined ||
+    value === "starting" ||
+    value === "active" ||
+    value === "completed" ||
+    value === "failed" ||
+    value === "cancelled" ||
+    value === "orphaned"
+  );
+}
+
+function isOptionalJoinStatus(value: unknown): boolean {
+  return (
+    value === undefined ||
+    value === "completed" ||
+    value === "failed" ||
+    value === "cancelled" ||
+    value === "timeout" ||
+    value === "unknown" ||
+    value === "waiting"
+  );
+}
+
+function isOptionalWaitReason(value: unknown): boolean {
+  return value === undefined || value === "dependency" || value === "rate_limit" || value === "child_running" || value === "unknown";
+}
+
+function isValidDuration(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER;
+}
+
+function resolveRequestedWaitJoinId(options: ObservMeWaitJoinOptions, kind: "wait" | "join"): string | undefined {
+  return options.id ?? (options.spawnId ? `${kind}-${options.spawnId}` : undefined);
+}
+
 function readSessionId(session: ObservMeTelemetrySession): string | undefined {
   const value = session.sessionAttributes?.[SESSION_ATTRIBUTES.PI_SESSION_ID];
   return typeof value === "string" ? value : undefined;

package/src/semconv/metrics.ts

@@ -66,6 +66,12 @@ export const OBSERVME_HISTOGRAM_METRIC_NAMES = {
 export const OBSERVME_GAUGE_METRIC_NAMES = {
   ACTIVE_SPANS: "observme_active_spans",
   ACTIVE_AGENTS: "observme_active_agents",
+  AGENT_LEASE_EXPIRES_UNIXTIME_SECONDS: "observme_agent_lease_expires_unixtime_seconds",
+} as const;
+
+export const OBSERVME_AGENT_LEASE_METRIC_OPTIONS = {
+  unit: "s",
+  description: "Absolute Unix timestamp in seconds when the active Pi agent lease expires.",
 } as const;
 
 export const OFFICIAL_GENAI_METRIC_NAMES = {