@openscout/protocol 0.2.63 → 0.2.82

package/src/invocations.ts

@@ -1,5 +1,7 @@
 import type { AgentHarness } from "./actors.js";
 import type { MetadataMap, ScoutId } from "./common.js";
+import type { ScoutPermissionProfile } from "./permission-policy.js";
+import type { ScoutExecutionResolution } from "./runtime-execution.js";
 
 export type InvocationAction =
   | "consult"
@@ -17,8 +19,59 @@ export type FlightState =
   | "failed"
   | "cancelled";
 
+export type InvocationSessionPolicy =
+  | "new"
+  | "reuse"
+  | "existing"
+  | "fork"
+  /** @deprecated use reuse */
+  | "any";
+
+/** Where a newly created harness session should be discoverable. */
+export type SessionPlacement = "background" | "foreground";
+
+export type InvocationForkSourceKind =
+  | "native_thread_clone"
+  | "scout_state_snapshot";
+
+export interface InvocationForkContextOptions {
+  maxMessages?: number;
+  maxBytes?: number;
+  includeBrokerRecords?: boolean;
+  includeObservedHarnessMaterial?: boolean;
+}
+
+export interface InvocationSessionLineage {
+  parentSessionId?: ScoutId;
+  parentHarnessThreadId?: string;
+  forkSourceKind?: InvocationForkSourceKind;
+  forkSourceId?: ScoutId | string;
+  forkedAt?: number;
+  metadata?: MetadataMap;
+}
+
 export interface InvocationExecutionPreference {
   harness?: AgentHarness;
+  model?: string;
+  reasoningEffort?: string;
+  permissionProfile?: ScoutPermissionProfile;
+  /**
+   * Background sessions use Scout-managed harness state. Foreground sessions
+   * use the operator's native harness state so the task is openable there.
+   */
+  placement?: SessionPlacement;
+  /**
+   * Controls whether work should enter fresh model context, opportunistically
+   * reuse a warm compatible session, continue one exact session, or fork a new
+   * execution session from prior state. The legacy "any" value is a
+   * compatibility alias for "reuse"; exact continuation requires targetSessionId.
+   */
+  session?: InvocationSessionPolicy;
+  targetSessionId?: ScoutId;
+  forkFromStateId?: ScoutId;
+  forkFromSessionId?: ScoutId;
+  forkContext?: InvocationForkContextOptions;
+  lineage?: InvocationSessionLineage;
 }
 
 export interface InvocationRequest {
@@ -34,9 +87,11 @@ export interface InvocationRequest {
   messageId?: ScoutId;
   context?: MetadataMap;
   execution?: InvocationExecutionPreference;
+  executionResolution?: ScoutExecutionResolution;
   ensureAwake: boolean;
   stream: boolean;
   timeoutMs?: number;
+  labels?: string[];
   createdAt: number;
   metadata?: MetadataMap;
 }
@@ -52,5 +107,303 @@ export interface FlightRecord {
   error?: string;
   startedAt?: number;
   completedAt?: number;
+  labels?: string[];
   metadata?: MetadataMap;
 }
+
+/**
+ * One concrete harness session used while executing a flight. Flights are the
+ * stable coordination handle; sessions are ephemeral execution resources and
+ * may change when a dispatch is retried, resumed, or replaced.
+ */
+export interface FlightSessionTraceEntry {
+  sessionId: ScoutId;
+  endpointId?: ScoutId;
+  nodeId?: ScoutId;
+  harness?: AgentHarness;
+  transport?: string;
+  strategy?: string;
+  placement?: SessionPlacement;
+  executionResolution?: ScoutExecutionResolution;
+  startedAt: number;
+  lastAcknowledgedAt: number;
+  endedAt?: number;
+}
+
+export interface FlightDispatchAcknowledgement {
+  sessionId?: ScoutId | null;
+  /**
+   * Provisional session id replaced by `sessionId` for this same dispatch.
+   * Absent for a real transition between two concrete provider sessions.
+   */
+  refinesSessionId?: ScoutId | null;
+  endpointId?: ScoutId | null;
+  nodeId?: ScoutId | null;
+  harness?: AgentHarness | null;
+  transport?: string | null;
+  strategy?: string | null;
+  placement?: SessionPlacement | null;
+  executionResolution?: ScoutExecutionResolution | null;
+  acknowledgedAt?: number | null;
+}
+
+function cleanTraceString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function cleanTraceTimestamp(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? value
+    : undefined;
+}
+
+function cleanTracePlacement(value: unknown): SessionPlacement | undefined {
+  return value === "background" || value === "foreground" ? value : undefined;
+}
+
+function parseFlightSessionTraceEntry(value: unknown): FlightSessionTraceEntry | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const sessionId = cleanTraceString(record.sessionId);
+  const startedAt = cleanTraceTimestamp(record.startedAt);
+  const lastAcknowledgedAt = cleanTraceTimestamp(record.lastAcknowledgedAt) ?? startedAt;
+  if (!sessionId || startedAt === undefined || lastAcknowledgedAt === undefined) return null;
+  const harness = cleanTraceString(record.harness);
+  const executionResolution = record.executionResolution
+    && typeof record.executionResolution === "object"
+    && !Array.isArray(record.executionResolution)
+    ? record.executionResolution as ScoutExecutionResolution
+    : undefined;
+  return {
+    sessionId,
+    ...(cleanTraceString(record.endpointId) ? { endpointId: cleanTraceString(record.endpointId) } : {}),
+    ...(cleanTraceString(record.nodeId) ? { nodeId: cleanTraceString(record.nodeId) } : {}),
+    ...(harness ? { harness: harness as AgentHarness } : {}),
+    ...(cleanTraceString(record.transport) ? { transport: cleanTraceString(record.transport) } : {}),
+    ...(cleanTraceString(record.strategy) ? { strategy: cleanTraceString(record.strategy) } : {}),
+    ...(cleanTracePlacement(record.placement) ? { placement: cleanTracePlacement(record.placement) } : {}),
+    ...(executionResolution ? { executionResolution } : {}),
+    startedAt,
+    lastAcknowledgedAt,
+    ...(cleanTraceTimestamp(record.endedAt) !== undefined
+      ? { endedAt: cleanTraceTimestamp(record.endedAt) }
+      : {}),
+  };
+}
+
+function parseDispatchAcknowledgement(value: unknown): FlightDispatchAcknowledgement | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const sessionId = cleanTraceString(record.sessionId);
+  const acknowledgedAt = cleanTraceTimestamp(record.acknowledgedAt);
+  if (!sessionId || acknowledgedAt === undefined) return null;
+  const harness = cleanTraceString(record.harness);
+  const executionResolution = record.executionResolution
+    && typeof record.executionResolution === "object"
+    && !Array.isArray(record.executionResolution)
+    ? record.executionResolution as ScoutExecutionResolution
+    : null;
+  return {
+    sessionId,
+    refinesSessionId: cleanTraceString(record.refinesSessionId) ?? null,
+    endpointId: cleanTraceString(record.endpointId) ?? null,
+    nodeId: cleanTraceString(record.nodeId) ?? null,
+    harness: harness ? harness as AgentHarness : null,
+    transport: cleanTraceString(record.transport) ?? null,
+    strategy: cleanTraceString(record.strategy) ?? null,
+    placement: cleanTracePlacement(record.placement) ?? null,
+    executionResolution,
+    acknowledgedAt,
+  };
+}
+
+/**
+ * Read a flight's ordered session history. Legacy records that only contain a
+ * dispatch acknowledgement are projected as a one-session trace.
+ */
+export function flightSessionTrace(
+  flightOrMetadata: Pick<FlightRecord, "metadata"> | MetadataMap | null | undefined,
+): FlightSessionTraceEntry[] {
+  const metadata = (
+    flightOrMetadata && "metadata" in flightOrMetadata
+      ? (flightOrMetadata as Pick<FlightRecord, "metadata">).metadata
+      : flightOrMetadata
+  ) as MetadataMap | null | undefined;
+  const recorded = Array.isArray(metadata?.sessionTrace)
+    ? metadata.sessionTrace
+      .map(parseFlightSessionTraceEntry)
+      .filter((entry): entry is FlightSessionTraceEntry => entry !== null)
+    : [];
+  if (recorded.length > 0) return recorded;
+
+  const dispatchAck = parseDispatchAcknowledgement(metadata?.dispatchAck);
+  if (!dispatchAck?.sessionId || dispatchAck.acknowledgedAt === null || dispatchAck.acknowledgedAt === undefined) {
+    return [];
+  }
+  return [{
+    sessionId: dispatchAck.sessionId,
+    ...(dispatchAck.endpointId ? { endpointId: dispatchAck.endpointId } : {}),
+    ...(dispatchAck.nodeId ? { nodeId: dispatchAck.nodeId } : {}),
+    ...(dispatchAck.harness ? { harness: dispatchAck.harness } : {}),
+    ...(dispatchAck.transport ? { transport: dispatchAck.transport } : {}),
+    ...(dispatchAck.strategy ? { strategy: dispatchAck.strategy } : {}),
+    ...(dispatchAck.placement ? { placement: dispatchAck.placement } : {}),
+    startedAt: dispatchAck.acknowledgedAt,
+    lastAcknowledgedAt: dispatchAck.acknowledgedAt,
+  }];
+}
+
+/** Append a dispatch acknowledgement without losing earlier session identity. */
+export function recordFlightSessionDispatch(
+  metadata: MetadataMap | null | undefined,
+  acknowledgement: unknown,
+): MetadataMap {
+  const dispatchAck = parseDispatchAcknowledgement(acknowledgement);
+  const nextMetadata: MetadataMap = { ...(metadata ?? {}), dispatchAck: acknowledgement };
+  if (!dispatchAck?.sessionId || dispatchAck.acknowledgedAt === null || dispatchAck.acknowledgedAt === undefined) {
+    return nextMetadata;
+  }
+
+  const trace = flightSessionTrace(metadata).map((entry) => ({ ...entry }));
+  const previous = trace.at(-1);
+  const refinesSameDispatch = Boolean(
+    previous
+    && dispatchAck.refinesSessionId
+    && previous.sessionId === dispatchAck.refinesSessionId
+    && previous.sessionId !== dispatchAck.sessionId
+    && previous.endpointId
+    && dispatchAck.endpointId
+    && previous.endpointId === dispatchAck.endpointId
+    && previous.startedAt === dispatchAck.acknowledgedAt,
+  );
+  if (
+    previous
+    && (previous.sessionId === dispatchAck.sessionId || refinesSameDispatch)
+    && (previous.endpointId ?? null) === (dispatchAck.endpointId ?? null)
+  ) {
+    // A transport can acknowledge with Scout's provisional routing id, then
+    // refine that same acknowledgement once the provider id is known. The
+    // unchanged endpoint and timestamp prove this is identity promotion, not
+    // a second harness session span.
+    if (refinesSameDispatch) {
+      previous.sessionId = dispatchAck.sessionId;
+    }
+    previous.lastAcknowledgedAt = Math.max(previous.lastAcknowledgedAt, dispatchAck.acknowledgedAt);
+    previous.strategy = dispatchAck.strategy ?? previous.strategy;
+    previous.placement = dispatchAck.placement ?? previous.placement;
+    previous.harness = dispatchAck.harness ?? previous.harness;
+    previous.transport = dispatchAck.transport ?? previous.transport;
+    previous.nodeId = dispatchAck.nodeId ?? previous.nodeId;
+    previous.executionResolution = dispatchAck.executionResolution ?? previous.executionResolution;
+    delete previous.endedAt;
+  } else {
+    if (previous && previous.endedAt === undefined) {
+      previous.endedAt = dispatchAck.acknowledgedAt;
+    }
+    trace.push({
+      sessionId: dispatchAck.sessionId,
+      ...(dispatchAck.endpointId ? { endpointId: dispatchAck.endpointId } : {}),
+      ...(dispatchAck.nodeId ? { nodeId: dispatchAck.nodeId } : {}),
+      ...(dispatchAck.harness ? { harness: dispatchAck.harness } : {}),
+      ...(dispatchAck.transport ? { transport: dispatchAck.transport } : {}),
+      ...(dispatchAck.strategy ? { strategy: dispatchAck.strategy } : {}),
+      ...(dispatchAck.placement ? { placement: dispatchAck.placement } : {}),
+      ...(dispatchAck.executionResolution ? { executionResolution: dispatchAck.executionResolution } : {}),
+      startedAt: dispatchAck.acknowledgedAt,
+      lastAcknowledgedAt: dispatchAck.acknowledgedAt,
+    });
+  }
+  nextMetadata.sessionTrace = trace;
+  return nextMetadata;
+}
+
+/**
+ * Mutable execution status for an invocation. Every field is optional — a
+ * freshly-created invocation has no flight or status yet.
+ *
+ * Note the dispatch job's scheduler state (attempts / leaseOwner /
+ * leaseExpiresAt / lastError) is deliberately NOT part of this: it is a distinct
+ * concern (worker-lease mechanics), stays its own journal-backed record, and is
+ * surfaced separately rather than folded into the domain status.
+ */
+export interface InvocationStatus {
+  /**
+   * Durable secondary id of the invocation's flight. Retained as a stable alias
+   * so projected run ids (`run:flight:<flightId>`) and follow links survive the
+   * flight→invocation storage merge.
+   */
+  flightId?: ScoutId;
+  state?: FlightState;
+  summary?: string;
+  output?: string;
+  error?: string;
+  startedAt?: number;
+  completedAt?: number;
+}
+
+/**
+ * The merged invocation record: the immutable request ({@link InvocationRequest})
+ * plus its mutable execution status ({@link InvocationStatus}). This is the
+ * single source of truth, from which the flight / work-item / agent-run views are
+ * projected. The standalone {@link FlightRecord} remains a compatibility shape
+ * over the same status subset.
+ */
+export type Invocation = InvocationRequest & InvocationStatus;
+
+export function normalizeInvocationSessionPolicy(
+  policy: InvocationSessionPolicy | string | null | undefined,
+): InvocationSessionPolicy | undefined {
+  switch (policy) {
+    case "new":
+    case "reuse":
+    case "existing":
+    case "fork":
+    case "any":
+      return policy;
+    default:
+      return undefined;
+  }
+}
+
+export function effectiveInvocationSessionPolicy(
+  execution: Pick<
+    InvocationExecutionPreference,
+    "session" | "targetSessionId" | "forkFromStateId" | "forkFromSessionId"
+  > | null | undefined,
+): Exclude<InvocationSessionPolicy, "any"> {
+  if (!execution) return "new";
+  if (execution.forkFromStateId || execution.forkFromSessionId || execution.session === "fork") {
+    return "fork";
+  }
+  if (execution.targetSessionId || execution.session === "existing") {
+    return "existing";
+  }
+  if (execution.session === "reuse" || execution.session === "any") {
+    return "reuse";
+  }
+  return "new";
+}
+
+export function validateInvocationExecutionPreference(
+  execution: InvocationExecutionPreference | null | undefined,
+): string[] {
+  if (!execution) return [];
+
+  const errors: string[] = [];
+  const policy = effectiveInvocationSessionPolicy(execution);
+
+  if (policy === "existing" && !execution.targetSessionId) {
+    errors.push("session existing requires targetSessionId");
+  }
+  if (policy === "fork" && !execution.forkFromStateId && !execution.forkFromSessionId) {
+    errors.push("session fork requires forkFromStateId or forkFromSessionId");
+  }
+  if (execution.session === "new" && execution.targetSessionId) {
+    errors.push("session new cannot target an existing session");
+  }
+  if (execution.session === "new" && (execution.forkFromStateId || execution.forkFromSessionId)) {
+    errors.push("session new cannot include fork source ids");
+  }
+
+  return errors;
+}

package/src/mesh.ts

@@ -1,5 +1,86 @@
 import type { AdvertiseScope, MetadataMap, ScoutId } from "./common.js";
 
+export const OPENSCOUT_MESH_PROTOCOL_VERSION = 1;
+export const OPENSCOUT_IROH_MESH_ALPN = "openscout/mesh/0";
+export const DEFAULT_OPENSCOUT_MESH_RENDEZVOUS_URL = "https://mesh.oscout.net";
+export const DEFAULT_OPENSCOUT_MOBILE_PAIRING_RELAY_URL = "wss://mesh.oscout.net/v1/relay";
+
+export type NodeMeshEntrypoint =
+  | IrohMeshEntrypoint
+  | CloudflareTunnelMeshEntrypoint
+  | HttpMeshEntrypoint
+  | MobilePairingMeshEntrypoint;
+
+export interface IrohMeshEntrypoint {
+  kind: "iroh";
+  endpointId: string;
+  endpointAddr: unknown;
+  alpn: typeof OPENSCOUT_IROH_MESH_ALPN;
+  bridgeProtocolVersion: typeof OPENSCOUT_MESH_PROTOCOL_VERSION;
+  lastSeenAt?: number;
+  expiresAt?: number;
+  metadata?: MetadataMap;
+}
+
+export interface CloudflareTunnelMeshEntrypoint {
+  kind: "cloudflare_tunnel";
+  url: string;
+  lastSeenAt?: number;
+  expiresAt?: number;
+  metadata?: MetadataMap;
+}
+
+export interface HttpMeshEntrypoint {
+  kind: "http";
+  url: string;
+  lastSeenAt?: number;
+  expiresAt?: number;
+  metadata?: MetadataMap;
+}
+
+export interface MobilePairingMeshEntrypoint {
+  kind: "mobile_pairing";
+  relay: string;
+  fallbackRelays?: string[];
+  room: string;
+  publicKey: string;
+  expiresAt: number;
+  lastSeenAt?: number;
+  metadata?: MetadataMap;
+}
+
+export type TrustedPeerTier = "observe" | "control";
+
+export type TrustedPeerGrantChannel = "sas" | "github" | "ssh";
+
+// A peer this node has enrolled into its trust cone (see
+// docs/proposals/mesh-trust-cone.md §6). All enrollment channels produce the
+// same artifact; revocation is soft via `revokedAt`.
+export interface TrustedPeerRecord {
+  /** Canonical machine identity: full SHA-256 hex of the DER public key. */
+  keyId: string;
+  /** Base64 DER spki Ed25519 public key. */
+  publicKey: string;
+  /** Short `osc1:xxxx-xxxx` form — display-only, never an identity key. */
+  fingerprint: string;
+  /** Remote node's runtime id, when known. */
+  nodeId?: ScoutId;
+  label: string;
+  tier: TrustedPeerTier;
+  grantedVia: TrustedPeerGrantChannel;
+  grantedAt: number;
+  expiresAt?: number;
+  revokedAt?: number;
+  lastSeenAt?: number;
+  /**
+   * §11.2 durable TLS pin: SHA-256 hex of the peer TLS certificate's
+   * SubjectPublicKeyInfo DER, copied from the peer's verified signed card at
+   * enrollment. Absent for Tailscale-path peers and pre-P1.5 enrollments.
+   */
+  tlsSpkiFingerprint?: string;
+  metadata?: MetadataMap;
+}
+
 export interface NodeDefinition {
   id: ScoutId;
   meshId: ScoutId;
@@ -7,6 +88,8 @@ export interface NodeDefinition {
   hostName?: string;
   advertiseScope: AdvertiseScope;
   brokerUrl?: string;
+  webUrl?: string;
+  meshEntrypoints?: NodeMeshEntrypoint[];
   tailnetName?: string;
   capabilities?: string[];
   labels?: string[];
@@ -14,3 +97,50 @@ export interface NodeDefinition {
   lastSeenAt?: number;
   registeredAt: number;
 }
+
+export interface OpenScoutMeshPresence {
+  v: typeof OPENSCOUT_MESH_PROTOCOL_VERSION;
+  meshId: ScoutId;
+  nodeId: ScoutId;
+  nodeName: string;
+  issuedAt: number;
+  expiresAt: number;
+  entrypoints: NodeMeshEntrypoint[];
+  signature?: {
+    algorithm: "ed25519";
+    keyId: string;
+    value: string;
+  };
+  metadata?: MetadataMap;
+}
+
+export interface OpenScoutMeshPresenceRecord extends OpenScoutMeshPresence {
+  observedAt: number;
+}
+
+export interface OpenScoutMeshRendezvousList {
+  v: typeof OPENSCOUT_MESH_PROTOCOL_VERSION;
+  meshId: ScoutId;
+  nodes: OpenScoutMeshPresenceRecord[];
+}
+
+export function buildUnsignedMeshPresence(input: {
+  node: Pick<NodeDefinition, "id" | "meshId" | "name">;
+  entrypoints: NodeMeshEntrypoint[];
+  issuedAt?: number;
+  ttlMs?: number;
+  metadata?: MetadataMap;
+}): OpenScoutMeshPresence {
+  const issuedAt = input.issuedAt ?? Date.now();
+  const ttlMs = input.ttlMs ?? 60_000;
+  return {
+    v: OPENSCOUT_MESH_PROTOCOL_VERSION,
+    meshId: input.node.meshId,
+    nodeId: input.node.id,
+    nodeName: input.node.name,
+    issuedAt,
+    expiresAt: issuedAt + ttlMs,
+    entrypoints: input.entrypoints,
+    ...(input.metadata ? { metadata: input.metadata } : {}),
+  };
+}

package/src/messages.ts

@@ -33,6 +33,8 @@ export interface MessageAudience {
   notify?: ScoutId[];
   invoke?: ScoutId[];
   reason?: DeliveryReason;
+  /** Persist the message without scheduling any transport deliveries. */
+  delivery?: "none";
 }
 
 export interface MessageRecord {

package/src/native-interactions.ts

@@ -0,0 +1,100 @@
+import type { ScoutId } from "./common.js";
+
+export type HarnessNativeInteractionKind =
+  | "question"
+  | "plan_approval"
+  | "task_projection"
+  | "subagent_activity"
+  | "tool_approval"
+  | "follow_up"
+  | "steer";
+
+export type ScoutNativeInteractionTargetKind =
+  | "question"
+  | "work_item"
+  | "invocation"
+  | "flight"
+  | "message"
+  | "session_projection";
+
+export interface HarnessNativeInteractionSource {
+  harness: string;
+  sessionId?: ScoutId;
+  harnessThreadId?: string;
+  toolCallId?: string;
+  nativeName?: string;
+  rawEventId?: string;
+}
+
+export interface HarnessNativeInteraction {
+  id: ScoutId;
+  kind: HarnessNativeInteractionKind;
+  source: HarnessNativeInteractionSource;
+  title?: string;
+  summary?: string;
+  payload?: Record<string, unknown>;
+  observedAt: number;
+}
+
+export interface HarnessNativeInteractionMapping {
+  kind: HarnessNativeInteractionKind;
+  nativeNames: string[];
+  scoutTargets: ScoutNativeInteractionTargetKind[];
+  description: string;
+}
+
+export const DEFAULT_HARNESS_NATIVE_INTERACTION_MAPPINGS: readonly HarnessNativeInteractionMapping[] = [
+  {
+    kind: "question",
+    nativeNames: ["ask_user"],
+    scoutTargets: ["question", "session_projection"],
+    description: "A harness-native user question becomes a Scout question.",
+  },
+  {
+    kind: "plan_approval",
+    nativeNames: ["submit_plan"],
+    scoutTargets: ["work_item", "session_projection"],
+    description: "A harness-native plan review becomes a Scout work item or review-needed projection.",
+  },
+  {
+    kind: "task_projection",
+    nativeNames: ["task_write", "task_update", "task_complete", "task_check"],
+    scoutTargets: ["work_item", "session_projection"],
+    description: "Harness-native task tools project into Scout work item task state.",
+  },
+  {
+    kind: "subagent_activity",
+    nativeNames: ["subagent"],
+    scoutTargets: ["invocation", "flight", "session_projection"],
+    description: "Harness-native child agent activity links to child invocations or observed child runs.",
+  },
+  {
+    kind: "tool_approval",
+    nativeNames: ["tool_approval_required"],
+    scoutTargets: ["session_projection"],
+    description: "A harness-native tool approval projects into session state.",
+  },
+  {
+    kind: "follow_up",
+    nativeNames: ["follow_up"],
+    scoutTargets: ["message", "session_projection"],
+    description: "A queued follow-up remains in the same conversation/session context.",
+  },
+  {
+    kind: "steer",
+    nativeNames: ["steer"],
+    scoutTargets: ["flight", "message", "session_projection"],
+    description: "A steering request redirects the active session or flight with an explicit reason.",
+  },
+] as const;
+
+export function scoutTargetsForNativeInteraction(
+  kind: HarnessNativeInteractionKind,
+): ScoutNativeInteractionTargetKind[] {
+  return [...(DEFAULT_HARNESS_NATIVE_INTERACTION_MAPPINGS.find(mapping => mapping.kind === kind)?.scoutTargets ?? [])];
+}
+
+export function nativeInteractionKindForName(nativeName: string): HarnessNativeInteractionKind | undefined {
+  const normalized = nativeName.trim();
+  return DEFAULT_HARNESS_NATIVE_INTERACTION_MAPPINGS.find(mapping => mapping.nativeNames.includes(normalized))?.kind;
+}