@opengeni/observability 1.4.4 → 1.4.5-canary.37458084490001

package/dist/agent-tool-metrics.d.ts

@@ -0,0 +1,25 @@
+import type { Observability } from "./index.js";
+/**
+ * Closed, low-cardinality families for agent tool calls. A tool's exact name,
+ * MCP server, connector domain, arguments, and output never become labels;
+ * unknown future tools collapse to `other` until reviewed here.
+ */
+export declare const AGENT_TOOL_METRIC_FAMILIES: readonly ["shell", "apply_patch", "browser", "computer", "human_handoff", "human_input", "image", "video", "web", "memory", "goal", "session", "machine", "skill", "tool_router", "files", "connector", "integration", "custom_mcp", "codemode", "other"];
+export type AgentToolMetricFamily = (typeof AGENT_TOOL_METRIC_FAMILIES)[number];
+export declare const AGENT_TOOL_CALL_OUTCOMES: readonly ["ok", "error", "rejected", "cancelled"];
+export type AgentToolCallOutcome = (typeof AGENT_TOOL_CALL_OUTCOMES)[number];
+/**
+ * Map the content-free analytics family computed for a tool call
+ * (`toolCallFamily`: a first-party tool name, `integration:<domain>`, or
+ * `custom`) — or, when absent, the model-facing tool name — onto the closed
+ * metric family set.
+ */
+export declare function agentToolMetricFamily(toolFamily: string | null | undefined, name?: string | null): AgentToolMetricFamily;
+/** Structural outcome of a normalized `agent.toolCall.output` payload. */
+export declare function agentToolCallOutcome(payload: unknown): AgentToolCallOutcome;
+/** Count one completed agent tool call. Telemetry failures never reach the turn. */
+export declare function recordAgentToolCall(observability: Observability | null | undefined, input: {
+    family: AgentToolMetricFamily;
+    outcome: AgentToolCallOutcome;
+    durationMs?: number;
+}): void;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { type TraceContext } from "./trace-context.js";
 import { type FailureDiagnosticInput } from "./failure-diagnostic.js";
 export type { FailureDiagnosticInput } from "./failure-diagnostic.js";
+export { AGENT_TOOL_CALL_OUTCOMES, AGENT_TOOL_METRIC_FAMILIES, agentToolCallOutcome, agentToolMetricFamily, recordAgentToolCall, type AgentToolCallOutcome, type AgentToolMetricFamily, } from "./agent-tool-metrics.js";
 export { failureDiagnostic } from "./failure-diagnostic.js";
 export { createLogThrottle, type LogThrottle } from "./log-throttle.js";
 export { withMcpTelemetry, withMcpCallIdentity, bindMcpTelemetry, beginMcpPhase, measureMcpPhase, recordToolApproval, MCP_EXECUTION_PHASES, } from "./mcp-timing.js";
@@ -150,6 +151,19 @@ export declare class Observability {
         status: number;
         durationSeconds: number;
     }): void;
+    /**
+     * Count a rejected API request by route, status, public error code, and a
+     * bounded reason (`permission:<name>`, a typed detail code, or
+     * `unclassified`). Values outside the closed grammars collapse to `other` so
+     * a malformed caller can never mint a free-form series.
+     */
+    recordHttpRejection(input: {
+        method: string;
+        route: string;
+        status: number;
+        code: string;
+        reason: string;
+    }): void;
     recordWorkerActivity(input: {
         activity: string;
         status: string;
@@ -220,6 +234,8 @@ export type InteractionOperationMetricObservation = {
     operation: string;
     outcome: string;
     mode: string;
+    /** Bounded failure reason; `none` for successful or non-failed outcomes. */
+    reason?: string | undefined;
     durationMs: number;
     replayed?: boolean | undefined;
 };

package/dist/index.js

@@ -291,6 +291,157 @@ function failureDiagnostic(input, revision) {
   };
 }
 
+// src/agent-tool-metrics.ts
+var AGENT_TOOL_METRIC_FAMILIES = [
+  "shell",
+  "apply_patch",
+  "browser",
+  "computer",
+  "human_handoff",
+  "human_input",
+  "image",
+  "video",
+  "web",
+  "memory",
+  "goal",
+  "session",
+  "machine",
+  "skill",
+  "tool_router",
+  "files",
+  "connector",
+  "integration",
+  "custom_mcp",
+  "codemode",
+  "other"
+];
+var AGENT_TOOL_CALL_OUTCOMES = ["ok", "error", "rejected", "cancelled"];
+var EXACT = {
+  exec_command: "shell",
+  write_stdin: "shell",
+  local_shell_call: "shell",
+  shell_call: "shell",
+  shell: "shell",
+  command_wait: "shell",
+  command_read: "shell",
+  interaction_discover: "browser",
+  interaction_request_human: "human_handoff",
+  request_human_input: "human_input",
+  wait_for_input: "human_input",
+  session_human_input_respond: "human_input",
+  generate_image: "image",
+  view_image: "image",
+  image_generation_call: "image",
+  generate_video: "video",
+  get_video_generation_capabilities: "video",
+  web_fetch: "web",
+  set_session_title: "session",
+  notify_user: "session",
+  set_other_session_title: "session",
+  sessions_list: "session",
+  sandboxes_list: "machine",
+  sandbox_attach: "machine",
+  sandbox_swap: "machine",
+  sandbox_provision: "machine",
+  run_on: "machine",
+  load_skill: "skill",
+  repository_skill_read: "skill",
+  tool_search: "tool_router",
+  tool_list: "tool_router",
+  tool_invoke: "tool_router",
+  sandbox_file_publish: "files",
+  google_drive_publish_file: "files",
+  custom_mcp_setup_request: "connector",
+  list_models: "other"
+};
+var PREFIXES = [
+  ["apply_patch", "apply_patch"],
+  ["browser_", "browser"],
+  ["computer_", "computer"],
+  ["web_search", "web"],
+  ["knowledge_", "memory"],
+  ["memory_", "memory"],
+  ["instruction_policy_", "memory"],
+  ["preference_", "memory"],
+  ["task_note", "memory"],
+  ["remember", "memory"],
+  ["company_profile_", "memory"],
+  ["work_claim_", "memory"],
+  ["goal_", "goal"],
+  ["session_", "session"],
+  ["project_", "session"],
+  ["rig_", "session"],
+  ["scheduled_task", "session"],
+  ["connected_machine_", "machine"],
+  ["skill_", "skill"],
+  ["artifacts_", "files"],
+  ["editable_artifact_", "files"],
+  ["files_", "files"],
+  ["slack_", "connector"],
+  ["fiken_", "connector"],
+  ["x_", "connector"],
+  ["reddit_", "connector"],
+  ["social_", "connector"],
+  ["github_", "connector"],
+  ["atlassian_", "connector"],
+  ["gmail_", "connector"],
+  ["variable_set_", "connector"],
+  ["environment_", "connector"],
+  ["capability_", "connector"]
+];
+function agentToolMetricFamily(toolFamily, name) {
+  if (toolFamily === "custom") return "custom_mcp";
+  if (toolFamily?.startsWith("integration:")) return "integration";
+  const candidate = (toolFamily ?? name ?? "").replace(/^(?:opengeni|interaction)__/, "").toLowerCase();
+  if (!candidate) return "other";
+  const exact = EXACT[candidate];
+  if (exact) return exact;
+  for (const [prefix, family] of PREFIXES) {
+    if (candidate.startsWith(prefix)) return family;
+  }
+  return "other";
+}
+var SDK_NOT_APPROVED = "Tool execution was not approved.";
+var SDK_TOOL_ERROR_PREFIX = "An error occurred while running the tool";
+function agentToolCallOutcome(payload) {
+  if (!payload || typeof payload !== "object") return "ok";
+  const record = payload;
+  if (record.error === true || record.failed === true) return "error";
+  const output = record.output;
+  if (output && typeof output === "object" && output.isError === true) {
+    return "error";
+  }
+  const text = typeof output === "string" ? output : output && typeof output === "object" && typeof output.text === "string" ? output.text : null;
+  if (text !== null) {
+    const trimmed = text.trim();
+    if (trimmed === SDK_NOT_APPROVED) return "rejected";
+    if (trimmed === "aborted") return "cancelled";
+    if (trimmed.startsWith(SDK_TOOL_ERROR_PREFIX)) return "error";
+  }
+  return "ok";
+}
+function recordAgentToolCall(observability, input) {
+  if (!observability) return;
+  const family = AGENT_TOOL_METRIC_FAMILIES.includes(input.family) ? input.family : "other";
+  const outcome = AGENT_TOOL_CALL_OUTCOMES.includes(input.outcome) ? input.outcome : "ok";
+  try {
+    observability.incrementCounter({
+      name: "opengeni_agent_tool_calls_total",
+      help: "Completed agent tool calls by closed tool family and structural outcome.",
+      labels: { family, outcome }
+    });
+    if (input.durationMs !== void 0 && Number.isFinite(input.durationMs)) {
+      observability.observeHistogram({
+        name: "opengeni_agent_tool_call_duration_seconds",
+        help: "Agent tool-call duration in seconds by closed tool family.",
+        labels: { family },
+        value: Math.max(0, input.durationMs) / 1e3
+      });
+    }
+  } catch {
+  }
+}
+
 // src/log-throttle.ts
 function createLogThrottle(options) {
   const intervalMs = Math.max(0, options.intervalMs);
@@ -553,10 +704,57 @@ var INTERACTION_OUTCOMES = /* @__PURE__ */ new Set([
   "dispatched",
   "completed",
   "failed",
+  "denied",
   "outcome_unknown",
   "stale",
   "cancelled"
 ]);
+var INTERACTION_OPERATION_REASONS = /* @__PURE__ */ new Set([
+  "none",
+  "resource_not_found",
+  "resource_unavailable",
+  "controller_stale",
+  "target_not_found",
+  "target_stale",
+  "observation_stale",
+  "document_stale",
+  "frame_stale",
+  "locator_not_found",
+  "locator_ambiguous",
+  "unsupported",
+  "permission_denied",
+  "machine_locked",
+  "attempt_stale",
+  "operation_conflict",
+  "outcome_unknown",
+  "invalid_action",
+  "timeout",
+  "controller_lost",
+  "driver_failed",
+  "action_failed",
+  "stale",
+  "unauthenticated",
+  "access_denied",
+  "not_found",
+  "conflict",
+  "invalid_request",
+  "rate_limited",
+  "unavailable",
+  "internal",
+  "rejected",
+  "control_unsupported",
+  "control_os",
+  "control_not_found",
+  "control_consent_required",
+  "control_timeout",
+  "control_draining",
+  "control_protocol",
+  "control_stream",
+  "control_agent_offline",
+  "control_fenced",
+  "control_payload_too_large",
+  "control_unknown"
+]);
 var INTERACTION_MODES = /* @__PURE__ */ new Set([
   "semantic",
   "coordinate",
@@ -649,10 +847,18 @@ var PUBLIC_TELEMETRY_ATTRIBUTE_KEYS = /* @__PURE__ */ new Set([
   "retainedOutputKind",
   "suppressedCount"
 ]);
+var HTTP_REJECTION_CODE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+var HTTP_REJECTION_REASON_PATTERN = /^(?:permission:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*|control:[a-z][a-z0-9_]{0,31}|[A-Za-z][A-Za-z0-9_.-]{0,63})$/;
 var PUBLIC_TELEMETRY_OPAQUE_ATTRIBUTE_PATTERNS = /* @__PURE__ */ new Map([
   ["mcpCallKey", /^mcp_[0-9a-f]{32}$/],
   ["sandboxLeaseKey", /^slk_[0-9a-f]{32}$/],
   ["correlationId", /^[A-Za-z0-9._:-]{1,128}$/],
+  // Rejected-request classification (apps/api/src/http/rejection-telemetry.ts):
+  // the public ErrorEnvelope code enum, a catalog permission or typed detail
+  // code, and a one-way message hash. Never message text or identifiers.
+  ["rejectionCode", HTTP_REJECTION_CODE_PATTERN],
+  ["rejectionReason", HTTP_REJECTION_REASON_PATTERN],
+  ["rejectionFingerprint", /^m_[0-9a-f]{10}$/],
   // Web error beacon: a route PATTERN of lowercase literal and `$param`
   // segments (never a concrete path or id) and the bundle revision token, in
   // the exact wire grammar the API route admits.
@@ -1073,6 +1279,26 @@ var Observability = class {
       }
     });
   }
+  /**
+   * Count a rejected API request by route, status, public error code, and a
+   * bounded reason (`permission:<name>`, a typed detail code, or
+   * `unclassified`). Values outside the closed grammars collapse to `other` so
+   * a malformed caller can never mint a free-form series.
+   */
+  recordHttpRejection(input) {
+    this.incrementCounter({
+      name: "opengeni_http_request_rejections_total",
+      help: "Rejected HTTP requests (status >= 400) by route, status, public error code, and bounded reason.",
+      labels: {
+        method: input.method,
+        route: input.route,
+        status: String(input.status),
+        code: HTTP_REJECTION_CODE_PATTERN.test(input.code) ? input.code : "other",
+        reason: HTTP_REJECTION_REASON_PATTERN.test(input.reason) ? input.reason : "other",
+        component: this.options.component
+      }
+    });
+  }
   recordWorkerActivity(input) {
     this.incrementCounter({
       name: "opengeni_worker_activity_runs_total",
@@ -1381,11 +1607,12 @@ function interactionOperationMetricObserver(observability) {
     const operation = boundedMetricEnum(INTERACTION_OPERATIONS, observation.operation);
     const outcome = boundedMetricEnum(INTERACTION_OUTCOMES, observation.outcome);
     const mode = boundedMetricEnum(INTERACTION_MODES, observation.mode);
+    const reason = boundedMetricEnum(INTERACTION_OPERATION_REASONS, observation.reason ?? "none");
     try {
       observability.incrementCounter({
         name: "opengeni_interaction_operations_total",
-        help: "Browser and Computer operations by bounded resource, operation, mode, and outcome.",
-        labels: { resource, operation, mode, outcome }
+        help: "Browser and Computer operations by bounded resource, operation, mode, outcome, and failure reason.",
+        labels: { resource, operation, mode, outcome, reason }
       });
       observability.observeHistogram({
         name: "opengeni_interaction_operation_duration_seconds",
@@ -1810,11 +2037,15 @@ async function defaultExporter(url, body, headers) {
   }
 }
 export {
+  AGENT_TOOL_CALL_OUTCOMES,
+  AGENT_TOOL_METRIC_FAMILIES,
   MCP_EXECUTION_PHASES,
   OPENGENI_OBSERVABILITY_DISTRIBUTION,
   Observability,
   TENANCY_COMPATIBILITY_LANES,
   admissionTraceContext,
+  agentToolCallOutcome,
+  agentToolMetricFamily,
   beginMcpPhase,
   bindMcpTelemetry,
   createLogThrottle,
@@ -1829,6 +2060,7 @@ export {
   measureMcpPhase,
   parseHeaders,
   parseTraceparent,
+  recordAgentToolCall,
   recordTenancyCompatibilityLaneUse,
   recordToolApproval,
   recordWorkflowWakeReconciliation,