@senad-d/observme 0.1.1 → 0.1.3

package/src/pi/integration-api.ts

@@ -0,0 +1,395 @@
+import {
+  OBSERVME_INTEGRATION_CHANNEL,
+  OBSERVME_INTEGRATION_VERSION,
+  type ObservMeCompleteSubagentOptions,
+  type ObservMeFailSubagentOptions,
+  type ObservMeIntegrationApi,
+  type ObservMeIntegrationContextSuccess,
+  type ObservMeIntegrationFailure,
+  type ObservMeIntegrationRequest,
+  type ObservMeIntegrationSuccess,
+  type ObservMeStartedSubagent,
+  type ObservMeStartedWaitJoin,
+  type ObservMeStartSubagentOptions,
+  type ObservMeWaitJoinOptions,
+} from "../integration.ts";
+import { SESSION_ATTRIBUTES } from "../semconv/attributes.ts";
+import {
+  completeSubagentSpawn,
+  endAgentJoin,
+  endAgentWait,
+  failSubagentSpawn,
+  startAgentJoin,
+  startAgentWait,
+  startSubagentSpawn,
+} from "./subagent-spawn.ts";
+import type { HandlerSessionState, ObservMeTelemetrySession } from "./handler-types.ts";
+
+interface IntegrationEventBus {
+  on(channel: string, handler: (data: unknown) => void): () => void;
+}
+
+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);
+  try {
+    return events.on(OBSERVME_INTEGRATION_CHANNEL, api.handleRequest.bind(api));
+  } catch {
+    return undefined;
+  }
+}
+
+export class SessionBackedObservMeIntegrationApi implements ObservMeIntegrationApi {
+  readonly version = OBSERVME_INTEGRATION_VERSION;
+  readonly #state: HandlerSessionState;
+
+  constructor(state: HandlerSessionState) {
+    this.#state = state;
+  }
+
+  handleRequest(value: unknown): void {
+    try {
+      if (!isCompatibleIntegrationRequest(value)) return;
+      value.respond(this);
+    } catch {
+      return;
+    }
+  }
+
+  getContext(): ObservMeIntegrationContextSuccess | ObservMeIntegrationFailure {
+    const session = this.#state.session;
+    if (!session) return integrationFailure("session_unavailable");
+
+    return {
+      ok: true,
+      context: {
+        workflowId: session.lineage.workflowId,
+        workflowRootAgentId: session.lineage.workflowRootAgentId,
+        agentId: session.lineage.agentId,
+        parentAgentId: session.lineage.parentAgentId,
+        rootAgentId: session.lineage.rootAgentId,
+        depth: session.lineage.depth,
+        role: session.lineage.role,
+        capability: session.lineage.capability,
+        sessionId: readSessionId(session),
+        traceId: readSessionTraceId(session),
+      },
+    };
+  }
+
+  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,
+        spawnId: started.spawnId,
+        childAgentId: started.childAgentId,
+        env: started.env,
+        traceContextPropagated: started.traceContextPropagated,
+      };
+    } catch {
+      return integrationFailure("operation_failed");
+    }
+  }
+
+  completeSubagent(
+    spawnId: string,
+    options: ObservMeCompleteSubagentOptions = {},
+  ): ObservMeIntegrationSuccess | ObservMeIntegrationFailure {
+    const session = this.#state.session;
+    if (!session) return integrationFailure("session_unavailable");
+    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 {
+      return integrationFailure("operation_failed");
+    }
+  }
+
+  failSubagent(
+    spawnId: string,
+    options: ObservMeFailSubagentOptions = {},
+  ): ObservMeIntegrationSuccess | ObservMeIntegrationFailure {
+    const session = this.#state.session;
+    if (!session) return integrationFailure("session_unavailable");
+    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 {
+      return integrationFailure("operation_failed");
+    }
+  }
+
+  startWait(options: ObservMeWaitJoinOptions = {}): ObservMeStartedWaitJoin | ObservMeIntegrationFailure {
+    return this.startWaitJoin(options, "wait");
+  }
+
+  endWait(
+    waitId: string,
+    options: ObservMeWaitJoinOptions = {},
+  ): ObservMeIntegrationSuccess | ObservMeIntegrationFailure {
+    return this.endWaitJoin(waitId, options, "wait");
+  }
+
+  startJoin(options: ObservMeWaitJoinOptions = {}): ObservMeStartedWaitJoin | ObservMeIntegrationFailure {
+    return this.startWaitJoin(options, "join");
+  }
+
+  endJoin(
+    joinId: string,
+    options: ObservMeWaitJoinOptions = {},
+  ): ObservMeIntegrationSuccess | ObservMeIntegrationFailure {
+    return this.endWaitJoin(joinId, options, "join");
+  }
+
+  private startWaitJoin(
+    options: ObservMeWaitJoinOptions,
+    kind: "wait" | "join",
+  ): 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 {
+      return integrationFailure("operation_failed");
+    }
+  }
+
+  private endWaitJoin(
+    id: string,
+    options: ObservMeWaitJoinOptions,
+    kind: "wait" | "join",
+  ): ObservMeIntegrationSuccess | ObservMeIntegrationFailure {
+    const session = this.#state.session;
+    if (!session) return integrationFailure("session_unavailable");
+    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();
+    } catch {
+      return integrationFailure("operation_failed");
+    }
+  }
+}
+
+function resolveIntegrationEventBus(pi: unknown): IntegrationEventBus | undefined {
+  if (!pi || typeof pi !== "object") return 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 {
+  if (!value || typeof value !== "object") return false;
+  const request = value as Partial<ObservMeIntegrationRequest>;
+  return (
+    Array.isArray(request.supportedVersions) &&
+    request.supportedVersions.includes(OBSERVME_INTEGRATION_VERSION) &&
+    typeof request.respond === "function"
+  );
+}
+
+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;
+}
+
+function readSessionTraceId(session: ObservMeTelemetrySession): string | undefined {
+  try {
+    return session.sessionSpan?.spanContext().traceId;
+  } catch {
+    return undefined;
+  }
+}
+
+function integrationSuccess(): ObservMeIntegrationSuccess {
+  return { ok: true };
+}
+
+function integrationFailure(reason: ObservMeIntegrationFailure["reason"]): ObservMeIntegrationFailure {
+  return { ok: false, reason };
+}

package/src/pi/subagent-spawn.ts

@@ -44,7 +44,7 @@ export type {
 
 export type SubagentSpawnType = "command" | "tool" | "extension" | "unknown";
 export type AgentJoinStatus = "completed" | "failed" | "cancelled" | "timeout" | "unknown" | "waiting";
-export type AttributePrimitive = boolean | number | string;
+export type AttributePrimitive = boolean | number | string | string[];
 export type AttributeMap = Record<string, AttributePrimitive>;
 
 export interface SubagentSpanRegistry {

package/tsconfig.json

@@ -11,5 +11,5 @@
     "allowImportingTsExtensions": true,
     "types": ["node"]
   },
-  "include": ["src/**/*.ts"]
+  "include": ["src/**/*.ts", "examples/**/*.ts"]
 }

package/ObservMe-Production-Docs/00-README.md

@@ -1,79 +0,0 @@
-# ObservMe Production Documentation
-
-**ObservMe** is a production-grade Pi extension for observability. It captures Pi session, turn, tool, LLM, branch, compaction, and error events, translates them into OpenTelemetry telemetry, and exports them to a durable external observability stack such as OpenTelemetry Collector, Grafana Tempo, Grafana Loki, Prometheus, Mimir, or Grafana Cloud.
-
-ObservMe is intentionally **not** a local analytics database. Pi agents are ephemeral. Observability data must leave the Pi agent process quickly, safely, and reliably. When multiple Pi agents or subagents are running, ObservMe must also preserve workflow and agent-tree lineage so operators can see which parent agent spawned each child agent and how the full orchestrated workload behaved.
-
-## Core Design
-
-```text
-Pi Agent
-  └── ObservMe Pi Extension
-        ├── OTEL Traces  ──► OTEL Collector ──► Tempo
-        ├── OTEL Metrics ──► OTEL Collector ──► Prometheus / Mimir
-        └── OTEL Logs    ──► OTEL Collector ──► Loki
-
-Grafana
-  ├── Tempo datasource
-  ├── Loki datasource
-  └── Prometheus/Mimir datasource
-```
-
-## Document Set
-
-| File | Purpose |
-|---|---|
-| `01-requirements-and-scope.md` | Product goals, non-goals, personas, requirements, rollout phases |
-| `02-reference-architecture.md` | Full system architecture and component responsibilities |
-| `03-pi-event-and-session-model.md` | Pi session/event sources and how ObservMe interprets them |
-| `04-telemetry-semantic-conventions.md` | ObservMe attribute, metric, log, and span naming specification |
-| `05-otel-pipeline-and-collector.md` | OTLP exporter strategy and production Collector configurations |
-| `06-security-privacy-redaction.md` | Prompt safety, secret redaction, PII handling, tenant isolation |
-| `07-extension-implementation-blueprint.md` | TypeScript implementation architecture, modules, lifecycle, code patterns |
-| `08-query-grafana-integration.md` | `/obs` commands, Grafana/Tempo/Loki/Prometheus query integration |
-| `09-dashboards-alerts-slos.md` | Dashboard pack, PromQL, LogQL, TraceQL, alerts, SLOs |
-| `10-testing-release-operations.md` | Test strategy, chaos testing, performance validation, release process |
-| `11-deployment-runbooks.md` | Local, Docker Compose, Kubernetes, and production runbooks |
-| `12-configuration-reference.md` | Complete ObservMe configuration schema and examples |
-| `13-source-notes.md` | Official documentation cross-check notes and external assumptions |
-| `pi-session-format.md` | Pi session JSONL reference copied and adapted from Pi's official session-format documentation |
-
-## Production Principles
-
-1. **OTLP-first.** ObservMe emits OpenTelemetry traces, metrics, and logs.
-2. **No durable local telemetry storage.** Only bounded in-memory queues are allowed.
-3. **Fail open.** If observability fails, Pi must continue operating.
-4. **Privacy by default.** Prompt and response content capture is disabled by default.
-5. **Pi-native and OTEL-compatible semantics.** ObservMe uses `observme.*` and `pi.*` for Pi-specific concepts and official OpenTelemetry `gen_ai.*` attributes where they fit; it does not depend on OpenInference.
-6. **Agent lineage by design.** Agent and subagent telemetry carries `pi.agent.*` lineage attributes and, where possible, W3C trace context so parent/child relationships survive process boundaries.
-7. **Workflow/tree observability.** Orchestrator workloads are modeled as agent trees with `pi.workflow.*` correlation, depth, fan-out, wait/join, orphan, and critical-path signals so operators can understand both single-agent and multi-agent execution.
-8. **Collector recommended.** Direct-to-backend export is allowed only for development or constrained environments.
-9. **Backend-neutral.** Tempo/Loki/Prometheus are reference backends, not hard dependencies.
-
-## Minimum Viable Production Release
-
-A production-ready `1.0.0` release must include:
-
-- Extension load and health checks
-- Session, workflow, agent-run, turn, LLM, tool, subagent-spawn, agent wait/join, compaction, branch, model-change telemetry
-- Multi-agent tree metrics for active agents, depth, fan-out, orphan agents, trace-context propagation failures, child failures, and workflow duration
-- OTLP trace exporter
-- OTLP metric exporter
-- OTLP log exporter
-- Configurable redaction and capture controls
-- Bounded queues and exporter timeouts
-- Grafana dashboard JSON
-- Collector reference configs
-- Tests for event mapping, redaction, exporter failure, and cardinality
-- `/obs status`, `/obs health`, `/obs session`, `/obs cost`, `/obs trace`, `/obs agents` commands
-
-## Source References
-
-This document set assumes:
-
-- Pi extensions provide documented lifecycle hooks, commands, tools, custom entries, session events, and queryable session state.
-- Pi can run multiple extension instances or spawn additional Pi processes through tools/subagent patterns; cross-process workflow and parent/child lineage requires explicit ObservMe correlation and trace-context propagation.
-- Pi sessions are JSONL files with typed entries such as `message`, `compaction`, `branch_summary`, `model_change`, `thinking_level_change`, `custom`, `custom_message`, `label`, and `session_info`.
-- OpenTelemetry Collector receives, processes, and exports telemetry via pipelines.
-- OpenTelemetry GenAI semantic conventions are the official OTEL namespace for GenAI client/agent spans, attributes, and metrics, but many GenAI fields are still experimental/evolving in SDK packages; ObservMe extends them for Pi-specific workflow concepts.
-- Grafana Tempo, Loki, and Prometheus/Mimir are reference storage systems for traces, logs, and metrics.