@ctliz/agent-intercom-pi 0.11.0-connect.2

package/broker/framing.ts

@@ -0,0 +1,87 @@
+import type { Socket } from "net";
+
+export const MAX_FRAME_BYTES = 1024 * 1024;
+
+/**
+ * Write a length-prefixed message to a socket.
+ * Format: 4-byte big-endian length + JSON payload
+ */
+export function writeMessage(socket: Socket, msg: unknown): void {
+  const json = JSON.stringify(msg);
+  const payload = Buffer.from(json, "utf-8");
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(payload.length, 0);
+  socket.write(Buffer.concat([header, payload]));
+}
+
+/**
+ * Create a message reader that handles partial reads.
+ * Calls onMessage for each complete message received.
+ * Protocol or handler errors are reported to onError so the caller can close the socket.
+ */
+export function createMessageReader(
+  onMessage: (msg: unknown) => void,
+  onError: (error: Error) => void,
+  maxFrameBytes = MAX_FRAME_BYTES,
+) {
+  let buffer = Buffer.alloc(0);
+
+  function reportMessage(payload: Buffer): boolean {
+    let msg: unknown;
+    try {
+      msg = JSON.parse(payload.toString("utf-8"));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      onError(new Error(`Failed to parse intercom message: ${message}`, { cause: error }));
+      return false;
+    }
+
+    try {
+      onMessage(msg);
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      onError(new Error(`Failed to handle intercom message: ${message}`, { cause: error }));
+      return false;
+    }
+  }
+
+  return (data: Buffer) => {
+    let remaining = data;
+
+    while (remaining.length > 0) {
+      if (buffer.length < 4) {
+        const headerBytes = Math.min(4 - buffer.length, remaining.length);
+        buffer = Buffer.concat([buffer, remaining.subarray(0, headerBytes)]);
+        remaining = remaining.subarray(headerBytes);
+        if (buffer.length < 4) {
+          return;
+        }
+      }
+
+      const length = buffer.readUInt32BE(0);
+      if (length > maxFrameBytes) {
+        buffer = Buffer.alloc(0);
+        onError(new Error(`Intercom frame length ${length} exceeds maximum ${maxFrameBytes} bytes`));
+        return;
+      }
+
+      const missingPayloadBytes = length - Math.max(0, buffer.length - 4);
+      const payloadBytes = Math.min(missingPayloadBytes, remaining.length);
+      if (payloadBytes > 0) {
+        buffer = Buffer.concat([buffer, remaining.subarray(0, payloadBytes)]);
+        remaining = remaining.subarray(payloadBytes);
+      }
+
+      if (buffer.length < 4 + length) {
+        return;
+      }
+
+      const payload = buffer.subarray(4, 4 + length);
+      buffer = Buffer.alloc(0);
+      if (!reportMessage(payload)) {
+        return;
+      }
+    }
+  };
+}

package/broker/ownership.ts

@@ -0,0 +1,61 @@
+import { closeSync, constants, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { INTERCOM_RUNTIME_FILE_MODE, restrictIntercomRuntimeFile } from "./paths.ts";
+
+function ownerPid(path: string): number | null {
+  try {
+    const pid = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function pidIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+export function acquireBrokerOwnership(path: string, pid = process.pid): void {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const fd = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, INTERCOM_RUNTIME_FILE_MODE);
+      try {
+        writeFileSync(fd, String(pid));
+      } finally {
+        closeSync(fd);
+      }
+      restrictIntercomRuntimeFile(path);
+      return;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const existingPid = ownerPid(path);
+      if (existingPid !== null && pidIsAlive(existingPid)) {
+        throw new Error(`Intercom broker already owned by live process ${existingPid}`);
+      }
+      try {
+        unlinkSync(path);
+      } catch (unlinkError) {
+        if ((unlinkError as NodeJS.ErrnoException).code !== "ENOENT") throw unlinkError;
+      }
+    }
+  }
+  throw new Error("Could not acquire intercom broker ownership");
+}
+
+export function releaseBrokerOwnership(path: string, pid = process.pid): void {
+  if (ownerPid(path) !== pid) return;
+  try {
+    unlinkSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+export function hasBrokerOwnership(path: string, pid = process.pid): boolean {
+  return ownerPid(path) === pid;
+}
+

package/broker/paths.ts

@@ -0,0 +1,161 @@
+import { chmodSync, mkdirSync, readFileSync } from "fs";
+import { isAbsolute, join, resolve } from "path";
+import { homedir } from "os";
+
+export const INTERCOM_DIR_MODE = 0o700;
+export const INTERCOM_RUNTIME_FILE_MODE = 0o600;
+export const INTERCOM_TCP_HOST = "127.0.0.1";
+export const INTERCOM_PROTOCOL_NAME = "pi-intercom";
+export const INTERCOM_PROTOCOL_VERSION = 4;
+
+export interface BrokerTcpEndpoint {
+  transport: "tcp";
+  host: string;
+  port: number;
+  stateId?: string;
+}
+
+export type BrokerConnectTarget = string | BrokerTcpEndpoint;
+
+function sanitizePipeSegment(value: string): string {
+  return value
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase() || "default";
+}
+
+export function getAgentDirPath(
+  env: NodeJS.ProcessEnv = process.env,
+  homeDir: string = homedir(),
+  cwd: string = process.cwd(),
+): string {
+  const configured = env.PI_CODING_AGENT_DIR?.trim();
+  if (!configured) {
+    return join(homeDir, ".pi/agent");
+  }
+
+  return isAbsolute(configured) ? configured : resolve(cwd, configured);
+}
+
+export function getIntercomDirPath(agentDir: string = getAgentDirPath()): string {
+  return join(agentDir, "intercom");
+}
+
+export function shouldUseWindowsTcpTransport(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  if (platform !== "win32") {
+    return false;
+  }
+
+  const transport = env.PI_INTERCOM_TRANSPORT?.trim().toLowerCase();
+  if (transport === "tcp") {
+    return true;
+  }
+
+  const legacyOptIn = env.PI_INTERCOM_TCP?.trim().toLowerCase();
+  return legacyOptIn === "1" || legacyOptIn === "true";
+}
+
+export function getBrokerPortFilePath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "broker.port.json");
+}
+
+export function getBrokerAskStateFilePath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "broker-asks.json");
+}
+
+export function getBrokerAccessStateFilePath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "broker-access.json");
+}
+
+export function getBrokerAdminCredentialFilePath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "broker-admin.json");
+}
+
+export function getBrokerAuditFilePath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "broker-audit.jsonl");
+}
+
+export function getRemoteGatewaySocketPath(
+  platform: NodeJS.Platform = process.platform,
+  agentDir: string = getAgentDirPath(),
+): string {
+  if (platform === "win32") {
+    return `\\\\.\\pipe\\pi-intercom-remote-${sanitizePipeSegment(agentDir)}`;
+  }
+  return join(getIntercomDirPath(agentDir), "remote-gateway.sock");
+}
+
+export function getBrokerSocketPath(
+  platform: NodeJS.Platform = process.platform,
+  agentDir: string = getAgentDirPath(),
+): string {
+  if (platform === "win32") {
+    return `\\\\.\\pipe\\pi-intercom-${sanitizePipeSegment(agentDir)}`;
+  }
+
+  return join(getIntercomDirPath(agentDir), "broker.sock");
+}
+
+export function getBrokerConnectTarget(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+  intercomDir: string = getIntercomDirPath(getAgentDirPath(env)),
+): BrokerConnectTarget {
+  if (shouldUseWindowsTcpTransport(platform, env)) {
+    const endpointFile = getBrokerPortFilePath(intercomDir);
+    const raw = readFileSync(endpointFile, "utf-8");
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`Invalid intercom TCP endpoint at ${endpointFile}: expected a JSON object`);
+    }
+    const endpoint = parsed as Record<string, unknown>;
+    if (
+      endpoint.transport !== "tcp"
+      || endpoint.host !== INTERCOM_TCP_HOST
+      || typeof endpoint.port !== "number"
+      || !Number.isSafeInteger(endpoint.port)
+      || endpoint.port <= 0
+      || endpoint.port > 65535
+      || typeof endpoint.stateId !== "string"
+      || endpoint.stateId.length === 0
+    ) {
+      throw new Error(`Invalid intercom TCP endpoint at ${endpointFile}`);
+    }
+    return { transport: "tcp", host: endpoint.host, port: endpoint.port, stateId: endpoint.stateId };
+  }
+
+  return getBrokerSocketPath(platform, getAgentDirPath(env));
+}
+
+export function getBrokerListenTarget(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): BrokerConnectTarget {
+  if (shouldUseWindowsTcpTransport(platform, env)) {
+    return { transport: "tcp", host: INTERCOM_TCP_HOST, port: 0 };
+  }
+
+  return getBrokerSocketPath(platform, getAgentDirPath(env));
+}
+
+export function ensureIntercomRuntimeDir(
+  intercomDir: string = getIntercomDirPath(),
+  platform: NodeJS.Platform = process.platform,
+): void {
+  mkdirSync(intercomDir, { recursive: true, mode: INTERCOM_DIR_MODE });
+  if (platform !== "win32") {
+    chmodSync(intercomDir, INTERCOM_DIR_MODE);
+  }
+}
+
+export function restrictIntercomRuntimeFile(
+  filePath: string,
+  platform: NodeJS.Platform = process.platform,
+): void {
+  if (platform !== "win32") {
+    chmodSync(filePath, INTERCOM_RUNTIME_FILE_MODE);
+  }
+}

package/broker/protected-service.ts

@@ -0,0 +1,158 @@
+import { types as nodeUtilTypes } from "node:util";
+import { BROKER_PROTECTED_PROVIDER_ROOT } from "@ctliz/agent-intercom-core/boss";
+
+export const PI_BOSS_PROTECTED_PROVIDER_ID = "pi" as const;
+export const PI_BOSS_PROTECTED_PROVIDER_PACKAGE = "@ctliz/agent-intercom-pi" as const;
+export const PI_BOSS_PROTECTED_PROVIDER_ARTIFACT_PATH =
+  `${BROKER_PROTECTED_PROVIDER_ROOT}${PI_BOSS_PROTECTED_PROVIDER_ID}/provider.mjs` as const;
+export const BOSS_PROTECTED_SERVICE_UNAVAILABLE = "BOSS_PROTECTED_SERVICE_UNAVAILABLE" as const;
+
+const PI_BOSS_PROTECTED_PROVIDER_MODE = "0555" as const;
+const CANONICAL_SEMANTIC_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:(?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const CANDIDATE_KEYS = [
+  "adapterId",
+  "providerPackage",
+  "providerVersion",
+  "providerDigest",
+  "artifactPath",
+  "artifactOwnerUid",
+  "artifactOwnerGid",
+  "artifactMode",
+] as const;
+
+export interface PiBossProtectedProviderArtifactCandidate {
+  adapterId: typeof PI_BOSS_PROTECTED_PROVIDER_ID;
+  providerPackage: typeof PI_BOSS_PROTECTED_PROVIDER_PACKAGE;
+  providerVersion: string;
+  providerDigest: string;
+  artifactPath: typeof PI_BOSS_PROTECTED_PROVIDER_ARTIFACT_PATH;
+  artifactOwnerUid: 0;
+  artifactOwnerGid: 0;
+  artifactMode: typeof PI_BOSS_PROTECTED_PROVIDER_MODE;
+}
+
+export type PiBossProtectedServiceErrorCode =
+  | "INVALID_PI_PROTECTED_PROVIDER_CANDIDATE"
+  | typeof BOSS_PROTECTED_SERVICE_UNAVAILABLE;
+
+export class PiBossProtectedServiceError extends Error {
+  readonly code: PiBossProtectedServiceErrorCode;
+  readonly path: string;
+
+  constructor(code: PiBossProtectedServiceErrorCode, path: string, message: string) {
+    super(`${path}: ${message}`);
+    this.name = "PiBossProtectedServiceError";
+    this.code = code;
+    this.path = path;
+  }
+}
+
+function invalid(path: string, message: string): never {
+  throw new PiBossProtectedServiceError("INVALID_PI_PROTECTED_PROVIDER_CANDIDATE", path, message);
+}
+
+function assertExactOwnDataCandidate(value: unknown): asserts value is Record<string, unknown> {
+  const path = "$candidate";
+  if (
+    typeof value !== "object"
+    || value === null
+    || nodeUtilTypes.isProxy(value)
+    || Array.isArray(value)
+    || Object.getPrototypeOf(value) !== Object.prototype
+  ) {
+    invalid(path, "must be a non-proxy plain data object");
+  }
+
+  const keys = Reflect.ownKeys(value);
+  if (
+    keys.length !== CANDIDATE_KEYS.length
+    || keys.some((key) => typeof key !== "string" || !CANDIDATE_KEYS.includes(key as typeof CANDIDATE_KEYS[number]))
+  ) {
+    invalid(path, "must contain exactly the canonical unsigned Pi provider candidate fields");
+  }
+
+  for (const key of CANDIDATE_KEYS) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (
+      descriptor === undefined
+      || !descriptor.enumerable
+      || !Object.hasOwn(descriptor, "value")
+    ) {
+      invalid(`${path}.${key}`, "must be an own enumerable data property");
+    }
+  }
+}
+
+function ownValue(value: Record<string, unknown>, key: typeof CANDIDATE_KEYS[number]): unknown {
+  return Object.getOwnPropertyDescriptor(value, key)!.value;
+}
+
+function readProviderVersion(value: unknown): string {
+  if (
+    typeof value !== "string"
+    || value.length > 128
+    || /[\r\n\u2028\u2029]/.test(value)
+    || !CANONICAL_SEMANTIC_VERSION.test(value)
+  ) {
+    invalid("$candidate.providerVersion", "must be a canonical semantic version");
+  }
+  return value;
+}
+
+function readProviderDigest(value: unknown): string {
+  if (typeof value !== "string" || value.length !== 64 || !/^[a-f0-9]{64}$/.test(value)) {
+    invalid("$candidate.providerDigest", "must be a lowercase SHA-256 digest");
+  }
+  return value;
+}
+
+/**
+ * Normalize an unsigned release candidate for the packaged Pi provider.
+ * This parser cannot verify installation, signatures, service identities, or
+ * authority. Its frozen result remains explicitly non-authoritative.
+ */
+export function parsePiBossProtectedProviderArtifactCandidate(
+  value: unknown,
+): Readonly<PiBossProtectedProviderArtifactCandidate> {
+  assertExactOwnDataCandidate(value);
+
+  if (ownValue(value, "adapterId") !== PI_BOSS_PROTECTED_PROVIDER_ID) {
+    invalid("$candidate.adapterId", "must identify the Pi provider");
+  }
+  if (ownValue(value, "providerPackage") !== PI_BOSS_PROTECTED_PROVIDER_PACKAGE) {
+    invalid("$candidate.providerPackage", "must identify the canonical Pi package");
+  }
+  if (ownValue(value, "artifactPath") !== PI_BOSS_PROTECTED_PROVIDER_ARTIFACT_PATH) {
+    invalid("$candidate.artifactPath", "must equal the canonical protected Pi provider path");
+  }
+  if (ownValue(value, "artifactOwnerUid") !== 0 || ownValue(value, "artifactOwnerGid") !== 0) {
+    invalid("$candidate.artifactOwnerUid", "must describe a root:root artifact");
+  }
+  if (ownValue(value, "artifactMode") !== PI_BOSS_PROTECTED_PROVIDER_MODE) {
+    invalid("$candidate.artifactMode", "must be read/execute-only mode 0555");
+  }
+
+  return Object.freeze({
+    adapterId: PI_BOSS_PROTECTED_PROVIDER_ID,
+    providerPackage: PI_BOSS_PROTECTED_PROVIDER_PACKAGE,
+    providerVersion: readProviderVersion(ownValue(value, "providerVersion")),
+    providerDigest: readProviderDigest(ownValue(value, "providerDigest")),
+    artifactPath: PI_BOSS_PROTECTED_PROVIDER_ARTIFACT_PATH,
+    artifactOwnerUid: 0,
+    artifactOwnerGid: 0,
+    artifactMode: PI_BOSS_PROTECTED_PROVIDER_MODE,
+  });
+}
+
+/**
+ * Production ensure is intentionally unavailable until a protected
+ * provisioner supplies release and service identity facts outside caller data.
+ * The request is never inspected while that provisioner is absent.
+ */
+export function ensurePiBossProtectedService(_request: unknown): never {
+  throw new PiBossProtectedServiceError(
+    BOSS_PROTECTED_SERVICE_UNAVAILABLE,
+    "$provisioner",
+    "the protected Pi broker service provisioner is not installed",
+  );
+}

package/broker/registration.ts

@@ -0,0 +1,173 @@
+import { types as nodeUtilTypes } from "node:util";
+import type { SessionRegistration } from "../types.ts";
+import { parseBossParticipantRegistrationMetadata } from "./boss-adapter.ts";
+
+const REQUIRED_SESSION_KEYS = ["cwd", "model", "pid", "startedAt", "lastActivity"] as const;
+const OPTIONAL_SESSION_KEYS = ["name", "status", "runtimeInstanceId", "boss"] as const;
+
+const MAX_SESSION_NAME_LENGTH = 256;
+const MAX_SESSION_CWD_LENGTH = 4096;
+const MAX_SESSION_MODEL_LENGTH = 512;
+const MAX_SESSION_STATUS_LENGTH = 512;
+const MAX_RUNTIME_INSTANCE_ID_LENGTH = 256;
+
+/**
+ * Reject every proxy in an authoritative graph before reflecting on that
+ * proxy. Descriptor traversal deliberately never invokes getters.
+ */
+export function assertNoProxyGraph(value: unknown): void {
+  const seen = new WeakSet<object>();
+  const visit = (candidate: unknown): void => {
+    if (typeof candidate !== "object" || candidate === null) return;
+    if (nodeUtilTypes.isProxy(candidate)) throw new Error("Proxies are not supported");
+    if (seen.has(candidate)) return;
+    seen.add(candidate);
+    for (const key of Reflect.ownKeys(candidate)) {
+      const descriptor = Object.getOwnPropertyDescriptor(candidate, key);
+      if (descriptor && Object.hasOwn(descriptor, "value")) visit(descriptor.value);
+    }
+  };
+  visit(value);
+}
+
+function isExactPlainDataRecord(
+  value: unknown,
+  requiredKeys: readonly string[],
+  optionalKeys: readonly string[],
+): value is Record<string, unknown> {
+  assertNoProxyGraph(value);
+  if (
+    typeof value !== "object"
+    || value === null
+    || Array.isArray(value)
+    || Object.getPrototypeOf(value) !== Object.prototype
+  ) return false;
+
+  const allowed = new Set([...requiredKeys, ...optionalKeys]);
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== "string" || !allowed.has(key))) return false;
+
+  for (const key of requiredKeys) {
+    if (!Object.hasOwn(value, key)) return false;
+  }
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value")) return false;
+  }
+  return true;
+}
+
+function dataValue(record: Record<string, unknown>, key: string): unknown {
+  return Object.getOwnPropertyDescriptor(record, key)?.value;
+}
+
+/** Exact ordinary/Boss session-registration discriminant. */
+export function parseSessionRegistration(value: unknown): SessionRegistration | null {
+  try {
+    if (!isExactPlainDataRecord(value, REQUIRED_SESSION_KEYS, OPTIONAL_SESSION_KEYS)) return null;
+
+    const cwd = dataValue(value, "cwd");
+    const model = dataValue(value, "model");
+    const pid = dataValue(value, "pid");
+    const startedAt = dataValue(value, "startedAt");
+    const lastActivity = dataValue(value, "lastActivity");
+    if (
+      typeof cwd !== "string"
+      || cwd.length === 0
+      || cwd.length > MAX_SESSION_CWD_LENGTH
+      || typeof model !== "string"
+      || model.length === 0
+      || model.length > MAX_SESSION_MODEL_LENGTH
+      || typeof pid !== "number"
+      || !Number.isFinite(pid)
+      || typeof startedAt !== "number"
+      || !Number.isFinite(startedAt)
+      || typeof lastActivity !== "number"
+      || !Number.isFinite(lastActivity)
+    ) return null;
+
+    const name = dataValue(value, "name");
+    if (name !== undefined && (typeof name !== "string" || name.length > MAX_SESSION_NAME_LENGTH)) return null;
+    const status = dataValue(value, "status");
+    if (status !== undefined && (typeof status !== "string" || status.length > MAX_SESSION_STATUS_LENGTH)) return null;
+    const runtimeInstanceId = dataValue(value, "runtimeInstanceId");
+    if (
+      runtimeInstanceId !== undefined
+      && (
+        typeof runtimeInstanceId !== "string"
+        || runtimeInstanceId.length === 0
+        || runtimeInstanceId.length > MAX_RUNTIME_INSTANCE_ID_LENGTH
+      )
+    ) return null;
+
+    if (Object.hasOwn(value, "boss")) {
+      const boss = dataValue(value, "boss");
+      if (boss === undefined) return null;
+      parseBossParticipantRegistrationMetadata(boss);
+    }
+    return value as SessionRegistration;
+  } catch {
+    return null;
+  }
+}
+
+/** Exact outer client register envelope, validated before nested registration data. */
+export function isExactClientRegistrationEnvelope(value: unknown): value is Record<string, unknown> & {
+  type: "register";
+  protocol: unknown;
+  version: unknown;
+  session: unknown;
+} {
+  try {
+    if (!isExactPlainDataRecord(
+      value,
+      ["type", "protocol", "version", "session"],
+      ["sessionId", "stateId", "access", "scopeId"],
+    )) return false;
+    return dataValue(value, "type") === "register";
+  } catch {
+    return false;
+  }
+}
+
+/** Exact outer client register frame with validated nested session data. */
+export function isExactClientRegistrationRequest(value: unknown): value is Record<string, unknown> & {
+  type: "register";
+  protocol: string;
+  version: number;
+  session: SessionRegistration;
+} {
+  return isExactClientRegistrationEnvelope(value)
+    && parseSessionRegistration(dataValue(value, "session")) !== null;
+}
+
+/** Exact outer registered frame for the one mode requested by this client. */
+export function isExactRegisteredFrame(
+  value: unknown,
+  mode: "ordinary" | "remote" | "boss",
+): value is Record<string, unknown> {
+  try {
+    const modeKeys = mode === "remote"
+      ? ["remoteAccess", "access"]
+      : mode === "boss"
+        ? ["capabilities", "boss"]
+        : [];
+    if (!isExactPlainDataRecord(
+      value,
+      ["type", "sessionId", "protocol", "version", ...modeKeys],
+      [],
+    )) return false;
+    return dataValue(value, "type") === "registered";
+  } catch {
+    return false;
+  }
+}
+
+/** Reads a frame discriminant without invoking accessors or inherited state. */
+export function readExactFrameType(value: unknown): string | null {
+  if (typeof value !== "object" || value === null || nodeUtilTypes.isProxy(value)) return null;
+  const descriptor = Object.getOwnPropertyDescriptor(value, "type");
+  return descriptor?.enumerable && Object.hasOwn(descriptor, "value") && typeof descriptor.value === "string"
+    ? descriptor.value
+    : null;
+}