@runuai/host 0.9.170 → 0.9.172

package/src/credential-location.ts

@@ -0,0 +1,248 @@
+/** Pure credential path grammar shared by capture and lease validation. */
+/** What a task may receive: a static key, or an OAuth login's brokered copy. */
+export const LEASE_PARAMETER_ROOT = "/uai/lease";
+/**
+ * The full OAuth material only the broker reads. Outside `/uai` altogether:
+ * `GetParametersByPath` returns every descendant of a path its caller may
+ * read, even one a Deny names, so containment comes from the root alone.
+ */
+export const BROKER_PARAMETER_ROOT = "/uai-broker";
+
+export type CredentialClass = "engine" | "mcp" | "github" | "ssh";
+export type CredentialScope = "org" | "user";
+
+/** Where one revision of one credential lives. */
+export interface CredentialLocation {
+  class: CredentialClass;
+  /** `github` and `ssh` are always `user`: one per person. */
+  scope: CredentialScope;
+  /** The org id for `org` scope, the user id for `user` scope. */
+  ownerId: string;
+  /** `engine` only: the engine kind (`codex`, `claude`, …). */
+  engineKind?: string;
+  /** `engine` and `mcp` only: the credential's stable id. */
+  credentialId?: string;
+  /** One immutable revision of the material. */
+  revision: string;
+}
+
+/** SSM allows `[A-Za-z0-9_.-]` in a path segment. An id that already fits,
+ *  starts with a letter or digit and has no dot is used as it is; any other
+ *  id is `-` followed by the hex of its UTF-8 bytes. No plain id starts with
+ *  `-`, so the mapping is injective. Legacy workspace ids
+ *  (`personal:<user>`) take the second form. */
+const PLAIN_ID_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const ENCODED_ID_SEGMENT = /^-(?:[0-9a-f]{2})+$/;
+const ENGINE_KIND = /^[a-z][a-z0-9-]{0,31}$/;
+export const MAX_CREDENTIAL_ID_CHARS = 128;
+/** SSM's limit for a parameter name, its ARN included. */
+export const MAX_PARAMETER_NAME_CHARS = 1011;
+
+export function isIdValue(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= MAX_CREDENTIAL_ID_CHARS &&
+    !/[\u0000-\u001f\u007f]/.test(value)
+  );
+}
+
+function utf8Hex(value: string): string {
+  let out = "";
+  for (const byte of new TextEncoder().encode(value)) {
+    out += byte.toString(16).padStart(2, "0");
+  }
+  return out;
+}
+
+function fromUtf8Hex(hex: string): string | null {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/** The path segment for an id (see `PLAIN_ID_SEGMENT`). Throws on an id no
+ *  segment may carry: empty, too long, or containing control characters. */
+export function idPathSegment(id: string): string {
+  if (!isIdValue(id)) throw new Error("invalid credential path id");
+  return PLAIN_ID_SEGMENT.test(id) ? id : `-${utf8Hex(id)}`;
+}
+
+/** Inverse of `idPathSegment`; null for a segment it never produces. */
+export function parseIdPathSegment(segment: string): string | null {
+  if (PLAIN_ID_SEGMENT.test(segment)) {
+    return segment.length <= MAX_CREDENTIAL_ID_CHARS ? segment : null;
+  }
+  if (!ENCODED_ID_SEGMENT.test(segment)) return null;
+  const id = fromUtf8Hex(segment.slice(1));
+  if (id === null || !isIdValue(id) || PLAIN_ID_SEGMENT.test(id)) return null;
+  return id;
+}
+
+export function isEngineKind(value: unknown): value is string {
+  return typeof value === "string" && ENGINE_KIND.test(value);
+}
+
+function locationSegments(location: CredentialLocation): string[] {
+  const owner = location.scope === "org" ? "orgs" : "users";
+  const segments = [owner, idPathSegment(location.ownerId)];
+  switch (location.class) {
+    case "engine": {
+      if (!isEngineKind(location.engineKind)) {
+        throw new Error("invalid engine kind");
+      }
+      if (location.credentialId === undefined) {
+        throw new Error("an engine credential needs its id");
+      }
+      segments.push(
+        "engines",
+        location.engineKind,
+        idPathSegment(location.credentialId),
+      );
+      break;
+    }
+    case "mcp": {
+      if (location.engineKind !== undefined) {
+        throw new Error("an MCP credential has no engine kind");
+      }
+      if (location.credentialId === undefined) {
+        throw new Error("an MCP credential needs its id");
+      }
+      segments.push("mcp", idPathSegment(location.credentialId));
+      break;
+    }
+    case "github":
+    case "ssh": {
+      if (location.scope !== "user") {
+        throw new Error(`${location.class} credentials belong to a user`);
+      }
+      if (
+        location.engineKind !== undefined ||
+        location.credentialId !== undefined
+      ) {
+        throw new Error(`${location.class} has one credential per person`);
+      }
+      segments.push(location.class);
+      break;
+    }
+    default:
+      throw new Error("invalid credential class");
+  }
+  segments.push(idPathSegment(location.revision));
+  return segments;
+}
+
+function nameUnder(root: string, location: CredentialLocation): string {
+  const name = `${root}/${locationSegments(location).join("/")}`;
+  if (name.length > MAX_PARAMETER_NAME_CHARS) {
+    throw new Error("credential parameter name too long");
+  }
+  return name;
+}
+
+/** The lease-readable parameter of one revision. */
+export function leaseParameterName(location: CredentialLocation): string {
+  return nameUnder(LEASE_PARAMETER_ROOT, location);
+}
+
+/** The broker-only parameter of one revision of an OAuth credential. GitHub
+ *  tokens and SSH keys are static and have none. */
+export function brokerParameterName(location: CredentialLocation): string {
+  if (location.class === "github" || location.class === "ssh") {
+    throw new Error(`${location.class} credentials have no broker part`);
+  }
+  return nameUnder(BROKER_PARAMETER_ROOT, location);
+}
+
+function parseUnder(root: string, name: string): CredentialLocation | null {
+  if (
+    typeof name !== "string" ||
+    name.length > MAX_PARAMETER_NAME_CHARS ||
+    !name.startsWith(`${root}/`)
+  ) {
+    return null;
+  }
+  const parts = name.slice(root.length + 1).split("/");
+  const [ownerKind, ownerSegment] = parts;
+  const scope: CredentialScope | null =
+    ownerKind === "orgs" ? "org" : ownerKind === "users" ? "user" : null;
+  if (scope === null || ownerSegment === undefined) return null;
+  const ownerId = parseIdPathSegment(ownerSegment);
+  if (ownerId === null) return null;
+  const revisionOf = (segment: string | undefined): string | null =>
+    segment === undefined ? null : parseIdPathSegment(segment);
+
+  if (parts[2] === "engines" && parts.length === 6) {
+    const credentialId = parseIdPathSegment(parts[4]!);
+    const revision = revisionOf(parts[5]);
+    if (!isEngineKind(parts[3]) || credentialId === null || revision === null) {
+      return null;
+    }
+    return {
+      class: "engine",
+      scope,
+      ownerId,
+      engineKind: parts[3],
+      credentialId,
+      revision,
+    };
+  }
+  if (parts[2] === "mcp" && parts.length === 5) {
+    const credentialId = parseIdPathSegment(parts[3]!);
+    const revision = revisionOf(parts[4]);
+    if (credentialId === null || revision === null) return null;
+    return { class: "mcp", scope, ownerId, credentialId, revision };
+  }
+  if (
+    (parts[2] === "github" || parts[2] === "ssh") &&
+    parts.length === 4 &&
+    scope === "user"
+  ) {
+    const revision = revisionOf(parts[3]);
+    if (revision === null) return null;
+    return { class: parts[2], scope, ownerId, revision };
+  }
+  return null;
+}
+
+export function parseLeaseParameterName(
+  name: string,
+): CredentialLocation | null {
+  return parseUnder(LEASE_PARAMETER_ROOT, name);
+}
+
+export function parseBrokerParameterName(
+  name: string,
+): CredentialLocation | null {
+  const location = parseUnder(BROKER_PARAMETER_ROOT, name);
+  return location && (location.class === "engine" || location.class === "mcp")
+    ? location
+    : null;
+}
+
+export function sameLocation(a: CredentialLocation, b: CredentialLocation): boolean {
+  return (
+    a.class === b.class &&
+    a.scope === b.scope &&
+    a.ownerId === b.ownerId &&
+    a.engineKind === b.engineKind &&
+    a.credentialId === b.credentialId &&
+    a.revision === b.revision
+  );
+}
+
+const TAG_VALUE = /^[\p{L}\p{Z}\p{N}_.:/=+\-@]{1,256}$/u;
+
+/** STS session tag and SSM resource tag values: the same grammar, refused
+ *  rather than rewritten, so a principal tag and a resource tag written for
+ *  one id always compare equal. */
+export function isTagValue(value: unknown): value is string {
+  return typeof value === "string" && TAG_VALUE.test(value);
+}
+

package/src/credential-wire-validation.ts

@@ -0,0 +1,25 @@
+/** Leaf structural wire validators. */
+type WireObject = Record<string, unknown>;
+export function exactObject(
+  value: unknown,
+  required: readonly string[],
+  optional: readonly string[] = [],
+): WireObject | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const object = value as WireObject;
+  const keys = Object.keys(object);
+  if (
+    keys.some(key => !required.includes(key) && !optional.includes(key)) ||
+    required.some((key) => !Object.hasOwn(object, key))
+  ) {
+    return null;
+  }
+  return object;
+}
+
+export function isPositiveInteger(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) > 0;
+}
+export function isEpochMs(value: unknown): value is number {
+  return isPositiveInteger(value);
+}

package/src/custom-connections.ts

@@ -0,0 +1,207 @@
+/** ADR-164: shared, secret-blind metadata and strictly bounded sealed settings.
+ * This module is pure and is re-exported by cloud-credentials and protocol. */
+import { parseCaptureFlowWire, parseCaptureResultWire, type CaptureFlowWire, type CaptureResultWire } from "./capture-wire";
+
+export const CUSTOM_CONNECTIONS_FEATURE = "customConnections";
+export const ENGINE_CONNECT_CUSTOM_FEATURE = "engineConnectCustom";
+export const ENGINE_CONNECT_CUSTOM_MANUAL_FEATURE = "engineConnectCustomManual";
+export const INTERNAL_CONNECTIONS_FEATURE = "internalConnections";
+export const CUSTOM_CONNECTION_REASONS = ["unreachable", "private-address", "unauthorized", "forbidden", "model-not-found", "wrong-protocol", "rate-limited", "timeout", "upstream-error", "invalid-models", "expired", "unsupported"] as const;
+export type CustomConnectionReason = typeof CUSTOM_CONNECTION_REASONS[number];
+export type CustomConnectionEngine = "claude" | "codex";
+export type CustomConnectionProvider = "openrouter" | "bedrock" | "custom";
+export type CustomConnectionTransport = "runtime" | "mantle";
+export type CustomConnectionAuthMode = "bearer" | "x-api-key";
+export type AccountBinding = "required" | "preferred";
+export const CUSTOM_CONNECTION_COMBINATIONS = ["openrouter:claude", "openrouter:codex", "bedrock:claude:runtime", "bedrock:codex:runtime", "bedrock:codex:mantle", "custom:claude", "custom:codex", "custom-internal:claude", "custom-internal:codex"] as const;
+export type CustomConnectionCombination = typeof CUSTOM_CONNECTION_COMBINATIONS[number];
+
+export interface CustomConnectionSettings {
+  providerType: CustomConnectionProvider;
+  /** Absent is public, for compatibility with existing revisions. */
+  internal?: boolean;
+  engine: CustomConnectionEngine;
+  baseUrl: string;
+  region?: string;
+  transport?: CustomConnectionTransport;
+  expiresAt?: number | null;
+  authMode: CustomConnectionAuthMode;
+}
+export interface CustomConnectionMaterial extends CustomConnectionSettings {
+  kind: "custom-connection";
+  apiKey: string;
+}
+/** The manifest deliberately has a host, never a URL or secret. */
+export interface CustomConnectionLease {
+  settingsHash: string;
+  providerType: CustomConnectionProvider;
+  /** Absent is public, for compatibility with existing revisions. */
+  internal?: boolean;
+  host: string;
+  region?: string;
+  transport?: CustomConnectionTransport;
+  expiresAt?: number | null;
+  models: string[];
+  defaultModel: string;
+  backgroundModel: string | null;
+  authMode: CustomConnectionAuthMode;
+}
+export interface OpenRouterBudget {
+  usage: number | null;
+  limit: number | null;
+  remaining: number | null;
+  effectiveBudget: number | null;
+  resetsAt: number | null;
+  keyExpiresAt: number | null;
+}
+export type OpenRouterBudgetResult = ({ status: "ok" } & OpenRouterBudget) | { status: "error"; reason: CustomConnectionReason };
+export type OpenRouterBudgetFrame = {
+  kind: "openrouter.budget"; taskId: string; credentialId: string; revision: string; observedAt: number;
+} & OpenRouterBudgetResult;
+
+export interface EngineConnectCustomDiscoverFrame {
+  kind: "engine.connect.custom.discover"; opId: string;
+  settings: CustomConnectionMaterial;
+  enabled: CustomConnectionCombination[];
+}
+export type CustomConnectionDiscoverResult = { ok: true; models: string[]; truncated?: boolean } | { ok: false; reason: CustomConnectionReason };
+export interface EngineConnectCustomDiscoveredFrame {
+  kind: "engine.connect.custom.discovered"; opId: string; result: CustomConnectionDiscoverResult;
+}
+export interface EngineConnectCustomSaveFrame {
+  kind: "engine.connect.custom.save"; opId: string;
+  settings: CustomConnectionMaterial;
+  enabled: CustomConnectionCombination[];
+  models: string[]; defaultModel: string; backgroundModel: string | null;
+  flow: CaptureFlowWire;
+}
+/** Internal connections have a distinct manual-only operation. */
+export interface EngineConnectCustomManualSaveFrame extends Omit<EngineConnectCustomSaveFrame, "kind"> {
+  kind: "engine.connect.custom.manual-save";
+}
+export type CustomConnectionSaveResult = { ok: true; capture: CaptureResultWire; authMode: CustomConnectionAuthMode; budget?: OpenRouterBudgetResult } | { ok: false; reason: CustomConnectionReason };
+export interface EngineConnectCustomSavedFrame {
+  kind: "engine.connect.custom.saved"; opId: string; result: CustomConnectionSaveResult;
+}
+
+export function connectionObject(value: unknown, required: readonly string[], optional: readonly string[] = []): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const o = value as Record<string, unknown>;
+  return required.every(k => Object.hasOwn(o, k)) && Object.keys(o).every(k => required.includes(k) || optional.includes(k)) ? o : null;
+}
+export function isCustomConnectionReason(v: unknown): v is CustomConnectionReason {
+  return typeof v === "string" && (CUSTOM_CONNECTION_REASONS as readonly string[]).includes(v);
+}
+export function parseCustomConnectionEnabled(v: unknown): CustomConnectionCombination[] | null {
+  return Array.isArray(v) && v.length <= CUSTOM_CONNECTION_COMBINATIONS.length && new Set(v).size === v.length && v.every(x => (CUSTOM_CONNECTION_COMBINATIONS as readonly unknown[]).includes(x)) ? [...v] : null;
+}
+export function customConnectionCombination(s: Pick<CustomConnectionSettings, "providerType" | "engine" | "transport" | "internal">): CustomConnectionCombination {
+  return `${s.providerType === "custom" && s.internal === true ? "custom-internal" : s.providerType}:${s.engine}${s.providerType === "bedrock" ? `:${s.transport}` : ""}` as CustomConnectionCombination;
+}
+export function customConnectionEnabled(s: Pick<CustomConnectionSettings, "providerType" | "engine" | "transport" | "internal">, enabled: readonly CustomConnectionCombination[]): boolean {
+  return enabled.includes(customConnectionCombination(s));
+}
+export function canonicalConnectionEndpoint(s: Pick<CustomConnectionSettings, "providerType" | "engine" | "region" | "transport">): string | null {
+  if (s.engine !== "claude" && s.engine !== "codex") return null;
+  if (s.providerType === "openrouter") return s.engine === "claude" ? "https://openrouter.ai/api" : "https://openrouter.ai/api/v1";
+  if (s.providerType !== "bedrock" || !s.region || !/^(?:[a-z]{2})(?:-[a-z]+){1,3}-[1-9][0-9]?$/.test(s.region)) return null;
+  if (s.transport === "runtime") return `https://bedrock-runtime.${s.region}.amazonaws.com${s.engine === "codex" ? "/openai/v1" : ""}`;
+  return s.transport === "mantle" && s.engine === "codex" ? `https://bedrock-mantle.${s.region}.api.aws/openai/v1` : null;
+}
+export function isCustomConnectionUrl(v: unknown, internal = false): v is string {
+  if (typeof v !== "string" || !v || v.length > 2048 || /[\s\u0000-\u001f\u007f]/.test(v) || v.endsWith("/")) return false;
+  try {
+    const u = new URL(v);
+    const hostname = u.hostname.replace(/^\[|\]$/g, "");
+    const dnsName = hostname.length <= 253 && hostname.replace(/\.$/, "").split(".").every(label => /^[A-Za-z0-9][A-Za-z0-9-]{0,62}$/.test(label));
+    return (u.protocol === "https:" || (internal && u.protocol === "http:")) && !u.username && !u.password && !u.search && !u.hash && ((u.hostname.startsWith("[") && u.hostname.endsWith("]")) || dnsName);
+  } catch { return false; }
+}
+export function parseCustomConnectionSettings(value: unknown): CustomConnectionSettings | null {
+  const o = connectionObject(value, ["providerType", "engine", "baseUrl", "authMode"], ["region", "transport", "expiresAt", "internal"]);
+  if (!o || !["openrouter", "bedrock", "custom"].includes(o.providerType as string) || !["claude", "codex"].includes(o.engine as string) || !isCustomConnectionUrl(o.baseUrl, o.providerType === "custom" && o.internal === true) || !["bearer", "x-api-key"].includes(o.authMode as string)) return null;
+  if (o.internal !== undefined && (typeof o.internal !== "boolean" || (o.internal && o.providerType !== "custom"))) return null;
+  const s = o as unknown as CustomConnectionSettings;
+  if (s.authMode !== "bearer" && !(s.providerType === "custom" && s.engine === "claude")) return null;
+  if (s.providerType === "bedrock") {
+    if (s.expiresAt !== null && s.expiresAt !== undefined && (!Number.isSafeInteger(s.expiresAt) || s.expiresAt <= 0)) return null;
+    if (s.baseUrl !== canonicalConnectionEndpoint(s)) return null;
+  } else if (o.region !== undefined || o.transport !== undefined || o.expiresAt !== undefined || (s.providerType === "openrouter" && s.baseUrl !== canonicalConnectionEndpoint(s))) return null;
+  return { ...s, ...(s.providerType === "custom" ? { baseUrl: new URL(s.baseUrl).href.replace(/\/$/, "") } : {}) };
+}
+export function parseCustomConnectionMaterial(value: unknown): CustomConnectionMaterial | null {
+  const o = connectionObject(value, ["kind", "providerType", "engine", "baseUrl", "apiKey", "authMode"], ["region", "transport", "expiresAt", "internal"]);
+  if (!o || o.kind !== "custom-connection" || typeof o.apiKey !== "string" || !o.apiKey || /\s|[\u0000-\u001f\u007f]/.test(o.apiKey) || new TextEncoder().encode(o.apiKey).length > 8192) return null;
+  const settings = Object.fromEntries(Object.entries(o).filter(([key]) => key !== "kind" && key !== "apiKey"));
+  const parsed = parseCustomConnectionSettings(settings);
+  return parsed ? { kind: "custom-connection", ...parsed, apiKey: o.apiKey } : null;
+}
+export function validConnectionModels(models: unknown, defaultModel: unknown, backgroundModel: unknown, engine: CustomConnectionEngine, key = ""): models is string[] {
+  return Array.isArray(models) && models.length >= 1 && models.length <= 200 && new Set(models).size === models.length && models.every(x => typeof x === "string" && x.length > 0 && x.length <= 200 && !/[\s\u0000-\u001f\u007f]/.test(x) && (!key || !x.includes(key))) && typeof defaultModel === "string" && models.includes(defaultModel) && (engine === "codex" ? backgroundModel === null : typeof backgroundModel === "string" && models.includes(backgroundModel));
+}
+export function parseCustomConnectionLease(value: unknown, engine: string): CustomConnectionLease | null {
+  const o = connectionObject(value, ["settingsHash", "providerType", "host", "models", "defaultModel", "backgroundModel", "authMode"], ["region", "transport", "expiresAt", "internal"]);
+  if (!o || typeof o.settingsHash !== "string" || !/^[a-f0-9]{64}$/.test(o.settingsHash) || typeof o.host !== "string" || !o.host || o.host.length > 253 || !validConnectionModels(o.models, o.defaultModel, o.backgroundModel, engine as CustomConnectionEngine)) return null;
+  const endpoint = canonicalConnectionEndpoint({ ...o, engine } as unknown as CustomConnectionSettings);
+  const settings = parseCustomConnectionSettings({ providerType: o.providerType, engine, baseUrl: endpoint ?? `https://${o.host}`, authMode: o.authMode, ...(o.internal !== undefined ? { internal: o.internal } : {}), ...(o.region !== undefined ? { region: o.region } : {}), ...(o.transport !== undefined ? { transport: o.transport } : {}), ...(o.expiresAt !== undefined ? { expiresAt: o.expiresAt } : {}) });
+  if (!settings || new URL(settings.baseUrl).host !== o.host) return null;
+  return { ...o } as unknown as CustomConnectionLease;
+}
+export function parseOpenRouterBudgetResult(value: unknown): OpenRouterBudgetResult | null {
+  const base = connectionObject(value, ["status", "reason"]);
+  if (base?.status === "error" && isCustomConnectionReason(base.reason)) return { status: "error", reason: base.reason };
+  const o = connectionObject(value, ["status", "usage", "limit", "remaining", "effectiveBudget", "resetsAt", "keyExpiresAt"]);
+  if (!o || o.status !== "ok" || !["usage", "limit", "remaining", "effectiveBudget"].every(k => o[k] === null || (typeof o[k] === "number" && Number.isFinite(o[k]) && (o[k] as number) >= 0)) || !["resetsAt", "keyExpiresAt"].every(k => o[k] === null || (Number.isSafeInteger(o[k]) && (o[k] as number) > 0))) return null;
+  return { ...o } as unknown as OpenRouterBudgetResult;
+}
+export function parseOpenRouterBudgetFrame(value: unknown): OpenRouterBudgetFrame | null {
+  const o = connectionObject(value, ["kind", "taskId", "credentialId", "revision", "observedAt", "status"], ["usage", "limit", "remaining", "effectiveBudget", "resetsAt", "keyExpiresAt", "reason"]);
+  if (!o || o.kind !== "openrouter.budget" || ![o.taskId, o.credentialId, o.revision].every(v => typeof v === "string" && v.length > 0 && v.length <= 128 && !/[\u0000-\u001f\u007f]/.test(v)) || !Number.isSafeInteger(o.observedAt) || (o.observedAt as number) <= 0) return null;
+  const { kind, taskId, credentialId, revision, observedAt, ...result } = o;
+  const parsed = parseOpenRouterBudgetResult(result);
+  return parsed ? { kind, taskId, credentialId, revision, observedAt, ...parsed } as OpenRouterBudgetFrame : null;
+}
+
+export function connectionOpId(v: unknown): v is string {
+  return typeof v === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(v);
+}
+export function parseEngineConnectCustomDiscoverFrame(value: unknown): EngineConnectCustomDiscoverFrame | null {
+  const o = connectionObject(value, ["kind", "opId", "settings", "enabled"]);
+  const settings = o ? parseCustomConnectionMaterial(o.settings) : null;
+  const enabled = o ? parseCustomConnectionEnabled(o.enabled) : null;
+  return o?.kind === "engine.connect.custom.discover" && connectionOpId(o.opId) && settings && enabled ? { kind: o.kind, opId: o.opId, settings, enabled } : null;
+}
+export function parseEngineConnectCustomSaveFrame(value: unknown): EngineConnectCustomSaveFrame | null {
+  const o = connectionObject(value, ["kind", "opId", "settings", "enabled", "models", "defaultModel", "backgroundModel", "flow"]);
+  const settings = o ? parseCustomConnectionMaterial(o.settings) : null;
+  const enabled = o ? parseCustomConnectionEnabled(o.enabled) : null;
+  const flow = o ? parseCaptureFlowWire(o.flow) : null;
+  if (!o || o.kind !== "engine.connect.custom.save" || !connectionOpId(o.opId) || !settings || !enabled || !flow || flow.location.class !== "engine" || flow.location.engineKind !== settings.engine || flow.brokerParameter !== null || !validConnectionModels(o.models, o.defaultModel, o.backgroundModel, settings.engine)) return null;
+  const wire: CaptureFlowWire = { credentialId: flow.credentialId, revision: flow.revision, leaseParameter: flow.leaseParameter, brokerParameter: flow.brokerParameter, orgId: flow.orgId, userId: flow.userId };
+  return { kind: o.kind, opId: o.opId, settings, enabled, models: [...o.models], defaultModel: o.defaultModel as string, backgroundModel: o.backgroundModel as string | null, flow: wire };
+}
+export function parseEngineConnectCustomManualSaveFrame(value: unknown): EngineConnectCustomManualSaveFrame | null {
+  if (!value || typeof value !== "object" || Array.isArray(value) || (value as Record<string, unknown>).kind !== "engine.connect.custom.manual-save") return null;
+  const parsed = parseEngineConnectCustomSaveFrame({ ...value, kind: "engine.connect.custom.save" });
+  return parsed?.settings.providerType === "custom" && parsed.settings.internal === true ? { ...parsed, kind: "engine.connect.custom.manual-save" } : null;
+}
+
+export function parseEngineConnectCustomDiscoveredFrame(value: unknown): EngineConnectCustomDiscoveredFrame | null {
+  const o = connectionObject(value, ["kind", "opId", "result"]);
+  if (!o || o.kind !== "engine.connect.custom.discovered" || !connectionOpId(o.opId)) return null;
+  const error = connectionObject(o.result, ["ok", "reason"]);
+  if (error?.ok === false && isCustomConnectionReason(error.reason)) return { kind: o.kind, opId: o.opId, result: { ok: false, reason: error.reason } };
+  const result = connectionObject(o.result, ["ok", "models"], ["truncated"]);
+  if (!result || result.ok !== true || (result.truncated !== undefined && typeof result.truncated !== "boolean") || !Array.isArray(result.models) || result.models.length > 2000 || new Set(result.models).size !== result.models.length || !result.models.every(x => typeof x === "string" && x.length > 0 && x.length <= 200 && !/[\s\u0000-\u001f\u007f]/.test(x))) return null;
+  return { kind: o.kind, opId: o.opId, result: { ok: true, models: [...result.models], ...(result.truncated === true ? { truncated: true } : {}) } };
+}
+export function parseEngineConnectCustomSavedFrame(value: unknown): EngineConnectCustomSavedFrame | null {
+  const o = connectionObject(value, ["kind", "opId", "result"]);
+  if (!o || o.kind !== "engine.connect.custom.saved" || !connectionOpId(o.opId)) return null;
+  const error = connectionObject(o.result, ["ok", "reason"]);
+  if (error?.ok === false && isCustomConnectionReason(error.reason)) return { kind: o.kind, opId: o.opId, result: { ok: false, reason: error.reason } };
+  const result = connectionObject(o.result, ["ok", "capture", "authMode"], ["budget"]);
+  const capture = result ? parseCaptureResultWire(result.capture) : null;
+  const budget = result?.budget === undefined ? undefined : parseOpenRouterBudgetResult(result.budget);
+  return result?.ok === true && capture && (result.authMode === "bearer" || result.authMode === "x-api-key") && budget !== null ? { kind: o.kind, opId: o.opId, result: { ok: true, capture, authMode: result.authMode, ...(budget ? { budget } : {}) } } : null;
+}