harnery 0.34.1 → 0.35.0

package/src/core/events/v3/runtime-telemetry-capabilities.ts

@@ -0,0 +1,137 @@
+import type { Adapter } from "../../adapter.ts";
+import {
+  adapterSignalSupportV3,
+  type CapabilitySupportV3,
+  type CursorExecutionModeV3,
+} from "./capabilities.ts";
+
+export type RuntimeTelemetryChannelV3 =
+  | "context_usage"
+  | "wait_spans"
+  | "wait_completeness"
+  | "response_latency"
+  | "inference_timing";
+
+export type RuntimeTelemetryCompletenessV3 = "exact" | "lower_bound" | "unknown";
+
+export interface RuntimeTelemetryCapabilityValueV3 {
+  support: Exclude<CapabilitySupportV3, "unsupported">;
+  source: string;
+  completeness: RuntimeTelemetryCompletenessV3;
+}
+
+export type RuntimeTelemetryCapabilityObservationV3 =
+  | {
+      state: "observed";
+      value: RuntimeTelemetryCapabilityValueV3;
+      attestation: "native" | "derived";
+      confidence: "exact" | "high";
+    }
+  | { state: "expected_but_missing"; capability: string; reason: string }
+  | { state: "unsupported"; capability: string };
+
+export type RuntimeContextCapabilityEvidenceV3 =
+  | {
+      state: "observed";
+      source: string;
+      attestation: "native" | "derived";
+      confidence: "exact" | "high";
+    }
+  | { state: "partial"; reason: string }
+  | { state: "unsupported" };
+
+export interface RuntimeTelemetryCapabilityEvidenceV3 {
+  adapter: Adapter;
+  cursor_mode?: CursorExecutionModeV3;
+  context: RuntimeContextCapabilityEvidenceV3;
+  canonical_turn_boundaries: boolean;
+  independent_wait_completeness?: boolean;
+}
+
+export type RuntimeTelemetryCapabilitiesV3 = Record<
+  RuntimeTelemetryChannelV3,
+  RuntimeTelemetryCapabilityObservationV3
+>;
+
+/**
+ * Resolve the telemetry support that one runtime session can actually prove.
+ *
+ * This is deliberately separate from AdapterCapabilityProfileV3. The static
+ * profile gates the event contract; this projection describes effective
+ * session evidence without moving a genesis-approved digest when a local
+ * source is missing, late, or unreadable.
+ */
+export function effectiveRuntimeTelemetryCapabilitiesV3(
+  evidence: RuntimeTelemetryCapabilityEvidenceV3,
+): RuntimeTelemetryCapabilitiesV3 {
+  return {
+    context_usage: contextCapability(evidence.context),
+    wait_spans: waitSpanCapability(evidence.adapter, evidence.cursor_mode),
+    wait_completeness: evidence.independent_wait_completeness
+      ? observed("native", "runtime.wait_aggregate", "exact", "native", "exact")
+      : unsupported("wait_turn_completeness"),
+    response_latency: evidence.canonical_turn_boundaries
+      ? observed("derived", "canonical.event_clocks", "exact", "derived", "exact")
+      : missing("response_latency", "turn_boundaries_not_delivered"),
+    inference_timing: unsupported("provider_inference_timing"),
+  };
+}
+
+function contextCapability(
+  evidence: RuntimeContextCapabilityEvidenceV3,
+): RuntimeTelemetryCapabilityObservationV3 {
+  if (evidence.state === "observed") {
+    return observed(
+      evidence.attestation === "native" ? "native" : "derived",
+      evidence.source,
+      "exact",
+      evidence.attestation,
+      evidence.confidence,
+    );
+  }
+  if (evidence.state === "partial") {
+    return missing("context_usage", evidence.reason);
+  }
+  return unsupported("context_usage");
+}
+
+function waitSpanCapability(
+  adapter: Adapter,
+  cursorMode: CursorExecutionModeV3 | undefined,
+): RuntimeTelemetryCapabilityObservationV3 {
+  if (adapter === "cursor" && cursorMode === "cloud") {
+    return unsupported("wait_span_delivery");
+  }
+  const support = adapterSignalSupportV3(adapter, "permission");
+  if (support === "unsupported") return unsupported("wait_span_delivery");
+  return observed(
+    support,
+    adapter === "cursor" ? "cursor.permission_hooks" : `${adapter}.permission_hooks`,
+    "lower_bound",
+    support === "native" ? "native" : "derived",
+    support === "native" ? "exact" : "high",
+  );
+}
+
+function observed(
+  support: Exclude<CapabilitySupportV3, "unsupported">,
+  source: string,
+  completeness: RuntimeTelemetryCompletenessV3,
+  attestation: "native" | "derived",
+  confidence: "exact" | "high",
+): RuntimeTelemetryCapabilityObservationV3 {
+  return {
+    state: "observed",
+    value: { support, source, completeness },
+    attestation,
+    confidence,
+  };
+}
+
+function missing(capability: string, reason: string): RuntimeTelemetryCapabilityObservationV3 {
+  return { state: "expected_but_missing", capability, reason };
+}
+
+function unsupported(capability: string): RuntimeTelemetryCapabilityObservationV3 {
+  return { state: "unsupported", capability };
+}

package/src/core/events/v3/turn-telemetry.ts

@@ -23,6 +23,16 @@ export interface TurnTelemetryV3 {
   usage: TelemetryObservationV3<TurnUsageV3>;
   inference: TelemetryObservationV3<TurnInferenceV3>;
   context: TelemetryObservationV3<ContextMeasurementV3>;
+  /** Private producer metadata; the context event persists only its safe fields. */
+  context_provenance?: ContextTelemetryProvenanceV3;
+}
+
+export interface ContextTelemetryProvenanceV3 {
+  source_event: string;
+  source_witness?: string;
+  runtime_version?: string;
+  attestation: "native" | "derived";
+  confidence: "exact" | "high";
 }
 
 export type TurnTelemetryCapabilitySupportV3 = Partial<

package/src/core/hooks/adapter/parse.ts

@@ -25,6 +25,9 @@ export interface ParsedPayload {
   cwd?: string;
   pid?: number;
   model?: string;
+  /** CC stamps the effective effort level ({level}) on tool hooks and Stop;
+   * absent on SessionStart/UserPromptSubmit and on models with no dial. */
+  effort?: string;
   source?: string; // SessionStart: "startup" | "resume" | …
   prompt?: string; // UserPromptSubmit / beforeSubmitPrompt
   agent_message?: string; // Cursor PreToolUse: user-visible assistant text before the tool
@@ -92,6 +95,7 @@ export function parsePayload(raw: string, adapter: Adapter): ParsedPayload | nul
     cwd: pickStr(json, "cwd"),
     pid: pickNum(json, "pid"),
     model: pickStr(json, "model"),
+    effort: pickEffortLevel(json),
     source: pickStr(json, "source"),
     prompt: pickStr(json, "prompt"),
     agent_message: pickStr(json, "agent_message"),
@@ -108,6 +112,18 @@ export function parsePayload(raw: string, adapter: Adapter): ParsedPayload | nul
   };
 }
 
+/** CC sends `effort` as an object ({"level":"high"}); tolerate a bare string
+ * in case an adapter flattens it. */
+function pickEffortLevel(json: Record<string, unknown>): string | undefined {
+  const effort = json.effort;
+  if (typeof effort === "string" && effort.length > 0) return effort;
+  if (typeof effort === "object" && effort !== null && !Array.isArray(effort)) {
+    const level = (effort as Record<string, unknown>).level;
+    if (typeof level === "string" && level.length > 0) return level;
+  }
+  return undefined;
+}
+
 /**
  * Cursor prefixes cloud/private-worker conversations with `bc-`. Current
  * sessionStart payloads also expose `is_background_agent`; either native