@senad-d/observme 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -30,6 +30,7 @@
 - Fixed session, workflow, agent, turn, LLM, tool, Bash, histogram, active-span, failure/recovery, and session-count telemetry accuracy.
 - Fixed lifecycle serialization, duplicate session replacement, bounded shutdown/flush behavior, backfill cancellation, parallel tool correlation, and bounded agent-tree state cleanup.
 - Hardened configuration validation, project-root path confinement, endpoint security, custom redaction patterns, tenant-salted hashing, and environment propagation.
+- Hardened integration discovery and lifecycle mutations against malformed providers, unsafe or oversized runtime inputs, and duplicate active spawn/wait/join identifiers.
 - Restored trusted-project redacted LLM capture and OpenAI Responses-style prompt capture while keeping capture disabled and redaction enabled by default.
 - Remediated SonarQube maintainability and security findings across parsing, regexes, fallback handling, diagnostics, and default assignment.
 - Fixed npm/CI dependency installation, package contents, README command drift, Grafana/Loki schema handling, and dashboard provisioning/query validation.

package/README.md

@@ -167,7 +167,9 @@ if (started?.ok) {
 }
 ```
 
-Use [`docs/extension-integration.md`](docs/extension-integration.md) for the complete lifecycle and API contract. The shipped [`examples/integrations/subagent-runner.ts`](examples/integrations/subagent-runner.ts) wraps a generic child transport, while [`docs/agent-subagent-observability-requirements.md`](docs/agent-subagent-observability-requirements.md) covers the larger orchestration design.
+The discovery helper fails open when the event bus or a provider is malformed. API methods also reject unsafe/oversized requests and duplicate active lifecycle IDs without replacing existing telemetry state. Handle every discriminated failure result locally and keep orchestration functional.
+
+Use [`docs/extension-integration.md`](docs/extension-integration.md) for the complete lifecycle, validation limits, and failure contract. The shipped [`examples/integrations/subagent-runner.ts`](examples/integrations/subagent-runner.ts) wraps a generic child transport, while [`docs/agent-subagent-observability-requirements.md`](docs/agent-subagent-observability-requirements.md) covers the larger orchestration design.
 
 ## Commands
 

package/docs/extension-integration.md

@@ -35,7 +35,7 @@ const observme: ObservMeIntegrationApi | undefined = requestObservMeIntegration(
 
 ObservMe registers no global object and does not require another extension to import its internal telemetry session. The event bus is the runtime boundary; the package subpath provides the stable constants, types, and request helper.
 
-The API can be absent when ObservMe is not installed, disabled by package configuration, not loaded yet, or incompatible. A method returns `{ ok: false, reason: "session_unavailable" }` when ObservMe is loaded but no telemetry session is active. Orchestration must remain functional in both cases and may run the child without ObservMe correlation after reporting a bounded local warning.
+The API can be absent when ObservMe is not installed, disabled by package configuration, not loaded yet, incompatible, or connected through a failing/malformed event-bus provider. A method returns `{ ok: false, reason: "session_unavailable" }` when ObservMe is loaded but no telemetry session is active. Orchestration must remain functional in both cases and may run the child without ObservMe correlation after reporting a bounded local warning.
 
 A package that cannot take a runtime dependency can implement the same synchronous request directly. Keep this channel and version stable:
 
@@ -118,9 +118,21 @@ Do not put raw tasks, prompts, command lines, environment values, child output,
 | `toolCallId` | Optional high-cardinality trace/log correlation when a tool initiated the spawn. |
 | `env` | Base child environment. ObservMe removes stale lineage/W3C keys and returns the replacement environment. |
 
+Runtime callers are validated even when JavaScript bypasses the TypeScript types. Caller-provided lifecycle identifiers must match `[A-Za-z0-9._:-]{1,128}`. Commands and individual arguments are capped at 4096 characters, argument lists at 256 items, and environment objects at 4096 entries. Durations must be finite, non-negative milliseconds. Invalid or duplicate active operations return a failure without replacing an existing span.
+
 Completion and wait/join methods use bounded child states (`starting`, `active`, `completed`, `failed`, `cancelled`, `orphaned`), join states (`waiting`, `completed`, `failed`, `cancelled`, `timeout`, `unknown`), and wait reasons (`dependency`, `rate_limit`, `child_running`, `unknown`). `failurePropagated=false` on a completed join confirms that the parent recovered from a failed child.
 
-All mutation methods return a discriminated result. Handle `session_unavailable`, `spawn_not_found`, `wait_not_found`, `join_not_found`, and `operation_failed` without crashing Pi. Do not retry a completed lifecycle handle blindly; repeated completion can otherwise hide an orchestration-state bug.
+All mutation methods return a discriminated result. Handle these reasons without crashing Pi:
+
+| Reason | Meaning |
+| --- | --- |
+| `session_unavailable` | ObservMe is loaded but no telemetry session is active. |
+| `invalid_request` | An identifier, enum, duration, command/argument field, or environment shape is invalid or oversized. |
+| `spawn_already_exists` / `wait_already_exists` / `join_already_exists` | The requested lifecycle identifier is already active. Generate a unique identifier or finish the active operation; do not overwrite it. |
+| `spawn_not_found` / `wait_not_found` / `join_not_found` | The lifecycle handle is absent or has already ended. |
+| `operation_failed` | ObservMe could not safely complete the operation. |
+
+Do not retry a completed lifecycle handle blindly; repeated completion can otherwise hide an orchestration-state bug.
 
 ## Propagation environment
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/observme",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "ObservMe: a Pi extension that instruments Pi agent sessions and exports OpenTelemetry traces, metrics, and logs to an external observability stack (OTel Collector, Grafana Tempo/Loki/Prometheus).",
   "license": "MIT",

package/src/integration.ts

@@ -10,6 +10,10 @@ export type ObservMeChildStatus = "starting" | "active" | "completed" | "failed"
 export type ObservMeJoinStatus = "completed" | "failed" | "cancelled" | "timeout" | "unknown" | "waiting";
 export type ObservMeIntegrationFailureReason =
   | "session_unavailable"
+  | "invalid_request"
+  | "spawn_already_exists"
+  | "wait_already_exists"
+  | "join_already_exists"
   | "spawn_not_found"
   | "wait_not_found"
   | "join_not_found"
@@ -118,17 +122,55 @@ interface IntegrationResponseHolder {
 }
 
 export function requestObservMeIntegration(host: ObservMeIntegrationHost): ObservMeIntegrationApi | undefined {
+  const events = resolveIntegrationEventBus(host);
+  if (!events) return undefined;
+
   const holder: IntegrationResponseHolder = {};
   const request: ObservMeIntegrationRequest = {
     supportedVersions: [OBSERVME_INTEGRATION_VERSION],
     respond: receiveObservMeIntegration.bind(undefined, holder),
   };
 
-  host.events.emit(OBSERVME_INTEGRATION_CHANNEL, request);
+  try {
+    events.emit(OBSERVME_INTEGRATION_CHANNEL, request);
+  } catch {
+    return undefined;
+  }
   return holder.api;
 }
 
-function receiveObservMeIntegration(holder: IntegrationResponseHolder, api: ObservMeIntegrationApi): void {
-  if (api.version !== OBSERVME_INTEGRATION_VERSION || holder.api) return;
-  holder.api = api;
+function resolveIntegrationEventBus(host: unknown): ObservMeIntegrationEventBus | undefined {
+  if (!host || typeof host !== "object") return undefined;
+  try {
+    const events = (host as Partial<ObservMeIntegrationHost>).events;
+    return events && typeof events.emit === "function" ? events : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function receiveObservMeIntegration(holder: IntegrationResponseHolder, value: unknown): void {
+  if (holder.api || !isObservMeIntegrationApi(value)) return;
+  holder.api = value;
+}
+
+function isObservMeIntegrationApi(value: unknown): value is ObservMeIntegrationApi {
+  if (!value || typeof value !== "object") return false;
+
+  try {
+    const api = value as Partial<ObservMeIntegrationApi>;
+    return (
+      api.version === OBSERVME_INTEGRATION_VERSION &&
+      typeof api.getContext === "function" &&
+      typeof api.startSubagent === "function" &&
+      typeof api.completeSubagent === "function" &&
+      typeof api.failSubagent === "function" &&
+      typeof api.startWait === "function" &&
+      typeof api.endWait === "function" &&
+      typeof api.startJoin === "function" &&
+      typeof api.endJoin === "function"
+    );
+  } catch {
+    return false;
+  }
 }

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;