harnery 0.32.0 → 0.34.0

package/src/core/events/v3/targets.ts

@@ -0,0 +1,182 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { type FingerprintContextV3, fingerprintV3 } from "./canonical.ts";
+import type { EventPayloadV3 } from "./contract.ts";
+
+export type TargetDescriptorV3 = EventPayloadV3<"tool.requested">["targets"][number];
+
+export interface ExtractTargetsV3Input {
+  coordRoot: string;
+  toolNamespace: string;
+  toolName: string;
+  toolInput: unknown;
+  fingerprintContext: FingerprintContextV3;
+}
+
+export interface DescribePathTargetV3Input {
+  coordRoot: string;
+  value: string;
+  access: TargetDescriptorV3["access"];
+  fingerprintContext: FingerprintContextV3;
+  extractorVersion: string;
+}
+
+/** Describe one known path without exposing values outside the coordination root. */
+export function describePathTargetV3(input: DescribePathTargetV3Input): TargetDescriptorV3 {
+  return pathTarget(
+    {
+      coordRoot: input.coordRoot,
+      fingerprintContext: input.fingerprintContext,
+    },
+    input.value,
+    input.access,
+    input.extractorVersion,
+  );
+}
+
+/** Versioned, tool-specific target extraction. Unknown tools deliberately emit no guessed target. */
+export function extractTargetsV3(input: ExtractTargetsV3Input): TargetDescriptorV3[] {
+  const record = plainRecord(input.toolInput);
+  if (!record) return [];
+  const name = input.toolName.toLowerCase();
+  const descriptors: TargetDescriptorV3[] = [];
+  const addPath = (value: unknown, access: TargetDescriptorV3["access"], version: string) => {
+    if (typeof value !== "string" || value.length === 0) return;
+    descriptors.push(pathTarget(input, value, access, version));
+  };
+  const addOpaque = (
+    kind: TargetDescriptorV3["kind"],
+    value: unknown,
+    access: TargetDescriptorV3["access"],
+    version: string,
+  ) => {
+    if (typeof value !== "string" || value.length === 0) return;
+    descriptors.push({
+      kind,
+      access,
+      fingerprint: fingerprintV3(
+        input.fingerprintContext,
+        `semantic-target.${kind}`,
+        value,
+        "root",
+      ),
+      extractor_version: version,
+    });
+  };
+
+  if (["read", "write", "edit", "multiedit", "notebookedit", "notebook_edit"].includes(name)) {
+    const access = name === "read" ? "read" : "write";
+    for (const field of ["file_path", "path", "notebook_path"]) {
+      addPath(record[field], access, "file-tool-v1");
+    }
+    if (Array.isArray(record.paths)) {
+      for (const path of record.paths) addPath(path, access, "file-tool-v1");
+    }
+  } else if (["grep", "search", "rg"].includes(name)) {
+    addPath(record.path, "read", "search-tool-v1");
+    addOpaque("pattern", record.pattern ?? record.query, "read", "search-tool-v1");
+  } else if (["glob", "find"].includes(name)) {
+    addPath(record.path, "read", "glob-tool-v1");
+    addOpaque("pattern", record.pattern ?? record.glob, "read", "glob-tool-v1");
+  } else if (["webfetch", "web_fetch", "fetch", "open"].includes(name)) {
+    addOpaque("url", record.url ?? record.ref_id, "read", "web-tool-v1");
+  } else if (["websearch", "web_search", "search_query"].includes(name)) {
+    addOpaque("query", record.query ?? record.q, "read", "web-search-v1");
+  } else if (["bash", "shell", "exec_command"].includes(name)) {
+    addPath(record.workdir ?? record.cwd, "execute", "command-tool-v1");
+  } else if (["artifact", "view_image", "image"].includes(name)) {
+    addPath(record.path ?? record.file_path, "read", "artifact-tool-v1");
+    addOpaque("artifact", record.artifact_id, "read", "artifact-tool-v1");
+  } else if (["apply_patch", "patch"].includes(name)) {
+    if (typeof record.patch === "string") {
+      for (const path of extractPatchPaths(record.patch)) addPath(path, "write", "patch-tool-v1");
+    }
+  }
+  return deduplicateTargets(descriptors);
+}
+
+export function exactToolInputFingerprintV3(
+  context: FingerprintContextV3,
+  toolNamespace: string,
+  toolName: string,
+  toolInput: unknown,
+) {
+  return fingerprintV3(context, "exact-input", {
+    tool_namespace: toolNamespace,
+    tool_name: toolName,
+    input: toolInput,
+  });
+}
+
+function pathTarget(
+  input: Pick<ExtractTargetsV3Input, "coordRoot" | "fingerprintContext">,
+  value: string,
+  access: TargetDescriptorV3["access"],
+  version: string,
+): TargetDescriptorV3 {
+  const root = resolve(input.coordRoot);
+  const valueUsesWindowsRoot = /^(?:[a-zA-Z]:[\\/]|\\\\)/.test(value);
+  const coordRootUsesWindowsRoot = /^(?:[a-zA-Z]:[\\/]|\\\\)/.test(input.coordRoot);
+  const valueUsesPosixRoot = value.startsWith("/");
+  const foreignAbsolute =
+    (valueUsesWindowsRoot && !coordRootUsesWindowsRoot) ||
+    (valueUsesPosixRoot && coordRootUsesWindowsRoot);
+  const resolved = resolve(root, value);
+  const relativePath = relative(root, resolved);
+  const contained =
+    !foreignAbsolute &&
+    relativePath !== ".." &&
+    !relativePath.startsWith(`..${sep}`) &&
+    !isAbsolute(relativePath);
+  if (contained) {
+    const portable = relativePath.length === 0 ? "." : relativePath.split(sep).join("/");
+    return {
+      kind: "workspace_path",
+      access,
+      display: portable,
+      fingerprint: fingerprintV3(
+        input.fingerprintContext,
+        "semantic-target.workspace-path",
+        portable,
+        "root",
+      ),
+      extractor_version: version,
+    };
+  }
+  return {
+    kind: "external_path",
+    access,
+    fingerprint: fingerprintV3(
+      input.fingerprintContext,
+      "semantic-target.external-path",
+      value.normalize("NFC").replaceAll("\\", "/"),
+      "root",
+    ),
+    extractor_version: version,
+  };
+}
+
+function extractPatchPaths(patch: string): string[] {
+  const paths: string[] = [];
+  for (const line of patch.split("\n")) {
+    const match = line.match(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/);
+    if (match?.[1]) paths.push(match[1]);
+  }
+  return paths;
+}
+
+function deduplicateTargets(targets: TargetDescriptorV3[]): TargetDescriptorV3[] {
+  const seen = new Set<string>();
+  return targets.filter((target) => {
+    const key = `${target.kind}\0${target.access}\0${target.fingerprint.digest}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function plainRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return undefined;
+  return value as Record<string, unknown>;
+}

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

@@ -0,0 +1,259 @@
+import type { Adapter } from "../../adapter.ts";
+import {
+  type AdapterSignalV3,
+  adapterSignalSupportV3,
+  type CapabilitySupportV3,
+} from "./capabilities.ts";
+import type { TurnHarnessV3, TurnInferenceV3, TurnUsageV3 } from "./contract.ts";
+
+export type TelemetryObservationV3<T> =
+  | { state: "observed"; value: T; attestation: "native" | "derived"; confidence: "exact" | "high" }
+  | { state: "unsupported"; capability: string }
+  | { state: "expected_but_missing"; capability: string; reason: string };
+
+export interface ContextMeasurementV3 {
+  used_tokens: number;
+  limit_tokens: number;
+  remaining_tokens?: number;
+  measured_at: string;
+  method: string;
+}
+
+export interface TurnTelemetryV3 {
+  usage: TelemetryObservationV3<TurnUsageV3>;
+  inference: TelemetryObservationV3<TurnInferenceV3>;
+  context: TelemetryObservationV3<ContextMeasurementV3>;
+}
+
+export type TurnTelemetryCapabilitySupportV3 = Partial<
+  Pick<
+    Record<AdapterSignalV3, CapabilitySupportV3>,
+    "model_usage" | "inference_timing" | "context_usage"
+  >
+>;
+
+export interface HarnessTimingAccumulatorV3 {
+  hook_time_ms: number;
+  hook_count: number;
+  slowest_hook?: string;
+  slowest_hook_ms: number;
+}
+
+/** Extract only telemetry explicitly reported by a hook/status payload. */
+export function extractTurnTelemetryV3(
+  adapter: Adapter,
+  payload: Record<string, unknown>,
+  observedAt = new Date().toISOString(),
+  support: TurnTelemetryCapabilitySupportV3 = {},
+): TurnTelemetryV3 {
+  const context =
+    record(payload.context_window) ??
+    record(payload.model_context_window) ??
+    record(payload.context_usage);
+  const usage =
+    record(payload.usage) ??
+    record(payload.token_usage) ??
+    record(context?.current_usage) ??
+    undefined;
+  const input = number(usage?.input_tokens);
+  const output = number(usage?.output_tokens);
+  const cacheRead = number(usage?.cache_read_tokens) ?? number(usage?.cache_read_input_tokens);
+  const cacheWrite =
+    number(usage?.cache_write_tokens) ?? number(usage?.cache_creation_input_tokens);
+  const usageObservation =
+    input !== undefined && output !== undefined
+      ? ({
+          state: "observed",
+          value: {
+            input_tokens: input,
+            output_tokens: output,
+            ...(cacheRead !== undefined ? { cache_read_tokens: cacheRead } : {}),
+            ...(cacheWrite !== undefined ? { cache_write_tokens: cacheWrite } : {}),
+            method: `${adapter.replaceAll("-", "_")}_hook`,
+          },
+          attestation: "native",
+          confidence: "exact",
+        } as const)
+      : missing(adapter, "model_usage", support.model_usage);
+
+  const inferenceMs =
+    number(payload.api_time_ms) ??
+    number(payload.inference_time_ms) ??
+    number(record(payload.timing)?.api_time_ms) ??
+    number(usage?.api_time_ms);
+  const requestCount =
+    number(payload.request_count) ?? number(record(payload.timing)?.request_count) ?? 1;
+  const inferenceObservation =
+    inferenceMs !== undefined
+      ? ({
+          state: "observed",
+          value: { api_time_ms: inferenceMs, request_count: requestCount },
+          attestation: "native",
+          confidence: "exact",
+        } as const)
+      : missing(adapter, "inference_timing", support.inference_timing);
+
+  const usedTokens =
+    number(context?.used_tokens) ??
+    number(context?.input_tokens) ??
+    number(context?.total_tokens) ??
+    number(payload.used_tokens) ??
+    number(payload.total_input_tokens) ??
+    number(usage?.total_tokens) ??
+    number(usage?.prompt_tokens) ??
+    (usage
+      ? sumDefined([
+          number(usage.input_tokens),
+          number(usage.cache_read_input_tokens),
+          number(usage.cache_creation_input_tokens),
+        ])
+      : undefined);
+  const limitTokens =
+    number(context?.context_window_size) ??
+    number(context?.window_tokens) ??
+    number(context?.context_window_tokens) ??
+    number(context?.max_tokens) ??
+    number(payload.context_window_size) ??
+    number(payload.context_window_tokens) ??
+    (typeof payload.context_window === "number" ? number(payload.context_window) : undefined);
+  const contextMeasurement = contextObservation(
+    adapter,
+    usedTokens,
+    limitTokens,
+    observedAt,
+    support.context_usage,
+  );
+
+  return { usage: usageObservation, inference: inferenceObservation, context: contextMeasurement };
+}
+
+function contextObservation(
+  adapter: Adapter,
+  usedTokens: number | undefined,
+  limitTokens: number | undefined,
+  observedAt: string,
+  override: CapabilitySupportV3 | undefined,
+): TelemetryObservationV3<ContextMeasurementV3> {
+  if (usedTokens !== undefined && limitTokens !== undefined && limitTokens > 0) {
+    return {
+      state: "observed",
+      value: {
+        used_tokens: usedTokens,
+        limit_tokens: limitTokens,
+        remaining_tokens: Math.max(0, limitTokens - usedTokens),
+        measured_at: observedAt,
+        method: `${adapter.replaceAll("-", "_")}_hook`,
+      },
+      attestation: "native",
+      confidence: "exact",
+    };
+  }
+
+  if (usedTokens !== undefined || limitTokens !== undefined) {
+    return {
+      state: "expected_but_missing",
+      capability: "context_usage",
+      reason:
+        usedTokens === undefined
+          ? "context_used_tokens_not_reported"
+          : limitTokens === undefined
+            ? "context_limit_tokens_not_reported"
+            : "context_limit_tokens_invalid",
+    };
+  }
+
+  return missing(adapter, "context_usage", override);
+}
+
+export function emptyHarnessTimingV3(): HarnessTimingAccumulatorV3 {
+  return { hook_time_ms: 0, hook_count: 0, slowest_hook_ms: 0 };
+}
+
+export function recordHarnessTimingV3(
+  accumulator: HarnessTimingAccumulatorV3,
+  hook: string,
+  durationMs: number,
+): HarnessTimingAccumulatorV3 {
+  const duration = safeInteger(durationMs);
+  if (duration === undefined) return accumulator;
+  const name = safeToken(hook, "unknown_hook");
+  return {
+    hook_time_ms: accumulator.hook_time_ms + duration,
+    hook_count: accumulator.hook_count + 1,
+    slowest_hook: duration >= accumulator.slowest_hook_ms ? name : accumulator.slowest_hook,
+    slowest_hook_ms: Math.max(duration, accumulator.slowest_hook_ms),
+  };
+}
+
+export function harnessObservationV3(
+  accumulator: HarnessTimingAccumulatorV3,
+): TelemetryObservationV3<TurnHarnessV3> {
+  return accumulator.hook_count > 0
+    ? {
+        state: "observed",
+        value: {
+          hook_time_ms: accumulator.hook_time_ms,
+          hook_count: accumulator.hook_count,
+          ...(accumulator.slowest_hook
+            ? {
+                slowest_hook: accumulator.slowest_hook,
+                slowest_hook_ms: accumulator.slowest_hook_ms,
+              }
+            : {}),
+        },
+        attestation: "derived",
+        confidence: "high",
+      }
+    : {
+        state: "expected_but_missing",
+        capability: "harness_timing",
+        reason: "no_hook_timing_samples",
+      };
+}
+
+function missing(
+  adapter: Adapter,
+  signal: "model_usage" | "inference_timing" | "context_usage",
+  override: CapabilitySupportV3 | undefined,
+) {
+  const declared = override ?? adapterSignalSupportV3(adapter, signal);
+  if (declared === "unsupported") return { state: "unsupported", capability: signal } as const;
+  return {
+    state: "expected_but_missing",
+    capability: signal,
+    reason:
+      signal === "model_usage"
+        ? "not_reported"
+        : declared === "conditional"
+          ? "conditional_signal_not_reported"
+          : "promised_signal_not_reported",
+  } as const;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function number(value: unknown): number | undefined {
+  return typeof value === "number" ? safeInteger(value) : undefined;
+}
+
+function safeInteger(value: number): number | undefined {
+  return Number.isFinite(value) && value >= 0 ? Math.floor(value) : undefined;
+}
+
+function sumDefined(values: Array<number | undefined>): number | undefined {
+  return values.some((value) => value !== undefined)
+    ? values.reduce<number>((total, value) => total + (value ?? 0), 0)
+    : undefined;
+}
+
+function safeToken(value: string, fallback: string): string {
+  const normalized = value
+    .normalize("NFC")
+    .replace(/[^a-zA-Z0-9._:/+-]/g, "_")
+    .slice(0, 128);
+  return /^[a-zA-Z0-9]/.test(normalized) ? normalized : fallback;
+}