@moretea-labs/forge 1.7.1 → 1.8.0

package/adapters/mcp/transports/session-registry.ts

@@ -0,0 +1,513 @@
+import { clearSessionCachesForSession } from '../../../src/cli/repository/session-cache';
+
+export type McpSessionRoute = '/mcp' | '/mcp-grok' | '/mcp-bearer' | '/recovery/mcp';
+
+export type McpSessionCloseReason =
+  | 'client_delete'
+  | 'transport_close'
+  | 'superseded'
+  | 'principal_capacity'
+  | 'capacity_eviction'
+  | 'idle_ttl'
+  | 'stream_lease'
+  | 'absolute_lifetime'
+  | 'tool_surface_changed'
+  | 'shutdown';
+
+export interface ClosableMcpTransport {
+  close(): Promise<void> | void;
+}
+
+export interface McpToolSurfaceRefresh {
+  toolSurfaceFingerprint: string;
+  toolNames?: string[];
+}
+
+export interface ManagedMcpSession<
+  TTransport extends ClosableMcpTransport = ClosableMcpTransport,
+  TContext = unknown,
+> {
+  sessionId: string;
+  transport: TTransport;
+  toolContext: TContext;
+  route: McpSessionRoute;
+  principalId: string;
+  /** Stable semantic connection identity; independent of MCP transport session id. */
+  connectionId: string;
+  clientIdentity: string;
+  toolSurfaceFingerprint?: string;
+  /** Exact tool names returned by the Canonical Runtime at initialize time. */
+  toolNames?: string[];
+  /** Standard MCP tools/list_changed notification bound to this session's connected Server. */
+  notifyToolListChanged?: () => Promise<void> | void;
+  /** Refreshes the mutable Runtime schema snapshot backing this live MCP session. */
+  refreshToolSurface?: () => Promise<McpToolSurfaceRefresh | undefined>;
+  lastNotifiedToolSurfaceFingerprint?: string;
+  createdAt: number;
+  lastActivityAt: number;
+  streamOpenedAt?: number;
+  postOpenedAt?: number;
+  inFlightPosts: number;
+  inFlightGets: number;
+  pendingCloseReason?: McpSessionCloseReason;
+}
+
+export interface McpSessionCloseCounters {
+  clientDelete: number;
+  transportClose: number;
+  superseded: number;
+  principalCapacity: number;
+  capacityEviction: number;
+  idleTtl: number;
+  streamLease: number;
+  absoluteLifetime: number;
+  toolSurfaceChanged: number;
+  shutdown: number;
+}
+
+export interface McpSessionSnapshot {
+  active: number;
+  maximum: number;
+  capacityAvailable: number;
+  utilization: number;
+  admissionMode: 'immediate' | 'eviction' | 'blocked';
+  acceptingNewSessions: boolean;
+  evictable: number;
+  protected: number;
+  activePosts: number;
+  activeStreams: number;
+  oldestStreamAgeMs: number;
+  oldestPostAgeMs: number;
+  recoveryRecommended: boolean;
+  closed: McpSessionCloseCounters;
+}
+
+export interface McpSessionRegistryOptions<
+  TTransport extends ClosableMcpTransport = ClosableMcpTransport,
+  TContext = unknown,
+> {
+  maximumSessions?: number;
+  maximumSessionsPerPrincipal?: number;
+  idleTtlMs?: number;
+  streamLeaseMs?: number;
+  absoluteLifetimeMs?: number;
+  activePostStallMs?: number;
+  now?: () => number;
+  onSessionClosed?: (session: ManagedMcpSession<TTransport, TContext>, reason: McpSessionCloseReason) => void;
+}
+
+interface RegisterMcpSession<TTransport extends ClosableMcpTransport, TContext> {
+  sessionId: string;
+  transport: TTransport;
+  toolContext: TContext;
+  route: McpSessionRoute;
+  principalId: string;
+  connectionId: string;
+  clientIdentity: string;
+  toolSurfaceFingerprint?: string;
+  toolNames?: string[];
+  notifyToolListChanged?: () => Promise<void> | void;
+  refreshToolSurface?: () => Promise<McpToolSurfaceRefresh | undefined>;
+  initialPost?: boolean;
+}
+
+interface InitializeCapacityRequest {
+  principalId: string;
+  connectionId: string;
+  route: McpSessionRoute;
+  maximumSessionsForPrincipal?: number;
+  enforcePrincipalCapacity?: boolean;
+  supersedeSessionId?: string;
+}
+
+interface InitializeReservation {
+  principalId: string;
+  connectionId: string;
+  route: McpSessionRoute;
+  createdAt: number;
+}
+
+const DEFAULT_MAXIMUM_SESSIONS = 64;
+const DEFAULT_IDLE_TTL_MS = 15 * 60_000;
+const DEFAULT_STREAM_LEASE_MS = 30 * 60_000;
+const DEFAULT_ABSOLUTE_LIFETIME_MS = 2 * 60 * 60_000;
+const DEFAULT_ACTIVE_POST_STALL_MS = 10 * 60_000;
+
+function positiveInteger(value: number | undefined, fallback: number): number {
+  return Number.isInteger(value) && (value ?? 0) > 0 ? value! : fallback;
+}
+
+function emptyCloseCounters(): McpSessionCloseCounters {
+  return {
+    clientDelete: 0,
+    transportClose: 0,
+    superseded: 0,
+    principalCapacity: 0,
+    capacityEviction: 0,
+    idleTtl: 0,
+    streamLease: 0,
+    absoluteLifetime: 0,
+    toolSurfaceChanged: 0,
+    shutdown: 0,
+  };
+}
+
+function counterForReason(reason: McpSessionCloseReason): keyof McpSessionCloseCounters {
+  switch (reason) {
+    case 'client_delete': return 'clientDelete';
+    case 'transport_close': return 'transportClose';
+    case 'superseded': return 'superseded';
+    case 'principal_capacity': return 'principalCapacity';
+    case 'capacity_eviction': return 'capacityEviction';
+    case 'idle_ttl': return 'idleTtl';
+    case 'stream_lease': return 'streamLease';
+    case 'absolute_lifetime': return 'absoluteLifetime';
+    case 'tool_surface_changed': return 'toolSurfaceChanged';
+    case 'shutdown': return 'shutdown';
+  }
+}
+
+export class McpSessionRegistry<
+  TTransport extends ClosableMcpTransport = ClosableMcpTransport,
+  TContext = unknown,
+> {
+  private readonly sessions = new Map<string, ManagedMcpSession<TTransport, TContext>>();
+  private readonly maximumSessions: number;
+  private readonly maximumSessionsPerPrincipal: number;
+  private readonly idleTtlMs: number;
+  private readonly streamLeaseMs: number;
+  private readonly absoluteLifetimeMs: number;
+  private readonly activePostStallMs: number;
+  private readonly now: () => number;
+  private readonly onSessionClosed?: (session: ManagedMcpSession<TTransport, TContext>, reason: McpSessionCloseReason) => void;
+  private readonly closeCounters = emptyCloseCounters();
+  private readonly initializeReservations = new Map<string, InitializeReservation>();
+  private admissionQueue: Promise<void> = Promise.resolve();
+  private nextReservationId = 0;
+
+  constructor(options: McpSessionRegistryOptions<TTransport, TContext> = {}) {
+    this.maximumSessions = positiveInteger(options.maximumSessions, DEFAULT_MAXIMUM_SESSIONS);
+    this.maximumSessionsPerPrincipal = Math.min(
+      this.maximumSessions,
+      positiveInteger(options.maximumSessionsPerPrincipal, this.maximumSessions),
+    );
+    this.idleTtlMs = positiveInteger(options.idleTtlMs, DEFAULT_IDLE_TTL_MS);
+    this.streamLeaseMs = positiveInteger(options.streamLeaseMs, DEFAULT_STREAM_LEASE_MS);
+    this.absoluteLifetimeMs = positiveInteger(options.absoluteLifetimeMs, DEFAULT_ABSOLUTE_LIFETIME_MS);
+    this.activePostStallMs = positiveInteger(options.activePostStallMs, DEFAULT_ACTIVE_POST_STALL_MS);
+    this.now = options.now ?? Date.now;
+    this.onSessionClosed = options.onSessionClosed;
+  }
+
+  get size(): number {
+    return this.sessions.size;
+  }
+
+  get(sessionId: string): ManagedMcpSession<TTransport, TContext> | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  values(): IterableIterator<ManagedMcpSession<TTransport, TContext>> {
+    return this.sessions.values();
+  }
+
+  register(input: RegisterMcpSession<TTransport, TContext>): ManagedMcpSession<TTransport, TContext> {
+    const now = this.now();
+    const session: ManagedMcpSession<TTransport, TContext> = {
+      ...input,
+      createdAt: now,
+      lastActivityAt: now,
+      ...(input.initialPost ? { postOpenedAt: now } : {}),
+      inFlightPosts: input.initialPost ? 1 : 0,
+      inFlightGets: 0,
+    };
+    this.sessions.set(input.sessionId, session);
+    return session;
+  }
+
+  touch(sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (session) session.lastActivityAt = this.now();
+  }
+
+  async notifyToolListChanged(currentFingerprint: string | undefined): Promise<number> {
+    if (!currentFingerprint) return 0;
+    let notified = 0;
+    await Promise.all(Array.from(this.sessions.values()).map(async (session) => {
+      if (!session.toolSurfaceFingerprint
+        || session.toolSurfaceFingerprint === currentFingerprint
+        || session.lastNotifiedToolSurfaceFingerprint === currentFingerprint
+        || !session.notifyToolListChanged) return;
+      try {
+        await session.notifyToolListChanged();
+        session.lastNotifiedToolSurfaceFingerprint = currentFingerprint;
+        notified += 1;
+      } catch {
+        // Fingerprint fencing remains authoritative. A broken notification
+        // stream must not mark a stale session as refreshed or close active work.
+      }
+    }));
+    return notified;
+  }
+
+  async refreshToolSurface(sessionId: string): Promise<McpToolSurfaceRefresh | undefined> {
+    const session = this.sessions.get(sessionId);
+    if (!session?.refreshToolSurface) return undefined;
+    const refreshed = await session.refreshToolSurface();
+    if (!refreshed?.toolSurfaceFingerprint) return undefined;
+    session.toolSurfaceFingerprint = refreshed.toolSurfaceFingerprint;
+    session.toolNames = refreshed.toolNames;
+    session.lastNotifiedToolSurfaceFingerprint = refreshed.toolSurfaceFingerprint;
+    session.lastActivityAt = this.now();
+    return refreshed;
+  }
+
+  beginPost(sessionId: string): ManagedMcpSession<TTransport, TContext> | undefined {
+    const session = this.sessions.get(sessionId);
+    if (!session) return undefined;
+    const now = this.now();
+    if (session.inFlightPosts === 0) session.postOpenedAt = now;
+    session.inFlightPosts += 1;
+    session.lastActivityAt = now;
+    return session;
+  }
+
+  endPost(sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    session.inFlightPosts = Math.max(0, session.inFlightPosts - 1);
+    if (session.inFlightPosts === 0) session.postOpenedAt = undefined;
+    session.lastActivityAt = this.now();
+  }
+
+  beginStream(sessionId: string): ManagedMcpSession<TTransport, TContext> | undefined {
+    const session = this.sessions.get(sessionId);
+    if (!session) return undefined;
+    const now = this.now();
+    if (session.inFlightGets === 0) session.streamOpenedAt = now;
+    session.inFlightGets += 1;
+    session.lastActivityAt = now;
+    return session;
+  }
+
+  endStream(sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    session.inFlightGets = Math.max(0, session.inFlightGets - 1);
+    if (session.inFlightGets === 0) session.streamOpenedAt = undefined;
+    session.lastActivityAt = this.now();
+  }
+
+  setPendingCloseReason(sessionId: string, reason: McpSessionCloseReason): void {
+    const session = this.sessions.get(sessionId);
+    if (session) session.pendingCloseReason = reason;
+  }
+
+  private retireSession(sessionId: string, reason: McpSessionCloseReason): ManagedMcpSession<TTransport, TContext> | undefined {
+    const session = this.sessions.get(sessionId);
+    if (!session) return undefined;
+    this.sessions.delete(sessionId);
+    clearSessionCachesForSession(sessionId);
+    session.pendingCloseReason = reason;
+    this.incrementCloseCounter(reason);
+    this.observeSessionClosed(session, reason);
+    return session;
+  }
+
+  private cleanupTransport(session: ManagedMcpSession<TTransport, TContext>): Promise<void> {
+    return Promise.resolve()
+      .then(() => session.transport.close())
+      .then(() => undefined)
+      .catch(() => undefined);
+  }
+
+  private closeForAdmission(sessionId: string, reason: McpSessionCloseReason): boolean {
+    const session = this.retireSession(sessionId, reason);
+    if (!session) return false;
+    // Admission authority is released synchronously. A slow peer/stream cleanup
+    // must not hold the serialized initialize lane after the registry has already
+    // fenced the old session out of routing.
+    void this.cleanupTransport(session);
+    return true;
+  }
+
+  detach(sessionId: string, reason: McpSessionCloseReason = 'transport_close'): boolean {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+    return Boolean(this.retireSession(sessionId, session.pendingCloseReason ?? reason));
+  }
+
+  async close(sessionId: string, reason: McpSessionCloseReason): Promise<boolean> {
+    const session = this.retireSession(sessionId, reason);
+    if (!session) return false;
+    await this.cleanupTransport(session);
+    return true;
+  }
+
+  private observeSessionClosed(session: ManagedMcpSession<TTransport, TContext>, reason: McpSessionCloseReason): void {
+    try {
+      this.onSessionClosed?.(session, reason);
+    } catch {
+      // Session close must remain available even if liveness evidence cannot be recorded.
+      // The controller lease then expires normally instead of being released unsafely.
+    }
+  }
+
+  async reserveForInitialize(request: InitializeCapacityRequest): Promise<string | undefined> {
+    return await this.withAdmissionLock(async () => {
+      await this.prune();
+
+      if (request.supersedeSessionId) {
+        const previous = this.sessions.get(request.supersedeSessionId);
+        if (previous
+          && previous.principalId === request.principalId
+          && previous.route === request.route
+          && previous.inFlightPosts === 0) {
+          this.closeForAdmission(previous.sessionId, 'superseded');
+        }
+      }
+
+      const principalLimit = Math.min(
+        this.maximumSessions,
+        positiveInteger(request.maximumSessionsForPrincipal, this.maximumSessionsPerPrincipal),
+      );
+      if (request.enforcePrincipalCapacity !== false) {
+        while (this.principalSessionCount(request.principalId) + this.principalReservationCount(request.principalId) + 1 > principalLimit) {
+          const candidate = this.safeCandidates((session) => session.principalId === request.principalId)[0];
+          if (!candidate) return undefined;
+          this.closeForAdmission(candidate.sessionId, 'principal_capacity');
+        }
+      }
+
+      while (this.sessions.size + this.initializeReservations.size + 1 > this.maximumSessions) {
+        const candidate = this.safeCandidates()[0];
+        if (!candidate) return undefined;
+        this.closeForAdmission(candidate.sessionId, 'capacity_eviction');
+      }
+
+      const reservationId = `initialize-${++this.nextReservationId}`;
+      this.initializeReservations.set(reservationId, {
+        principalId: request.principalId,
+        connectionId: request.connectionId,
+        route: request.route,
+        createdAt: this.now(),
+      });
+      return reservationId;
+    });
+  }
+
+  commitInitialize(
+    reservationId: string,
+    input: RegisterMcpSession<TTransport, TContext>,
+  ): ManagedMcpSession<TTransport, TContext> {
+    const reservation = this.initializeReservations.get(reservationId);
+    if (!reservation
+      || reservation.principalId !== input.principalId
+      || reservation.connectionId !== input.connectionId
+      || reservation.route !== input.route) {
+      throw new Error('MCP_INITIALIZE_RESERVATION_INVALID');
+    }
+    this.initializeReservations.delete(reservationId);
+    return this.register({ ...input, initialPost: true });
+  }
+
+  releaseInitialize(reservationId: string): void {
+    this.initializeReservations.delete(reservationId);
+  }
+
+  async prune(): Promise<void> {
+    const now = this.now();
+    const expired = [...this.sessions.values()]
+      .filter((session) => session.inFlightPosts === 0)
+      .map((session): { session: ManagedMcpSession<TTransport, TContext>; reason?: McpSessionCloseReason } => {
+        if (now - session.createdAt >= this.absoluteLifetimeMs) return { session, reason: 'absolute_lifetime' };
+        if (session.inFlightGets > 0 && session.streamOpenedAt !== undefined && now - session.streamOpenedAt >= this.streamLeaseMs) {
+          return { session, reason: 'stream_lease' };
+        }
+        if (session.inFlightGets === 0 && now - session.lastActivityAt >= this.idleTtlMs) return { session, reason: 'idle_ttl' };
+        return { session };
+      })
+      .filter((entry): entry is { session: ManagedMcpSession<TTransport, TContext>; reason: McpSessionCloseReason } => Boolean(entry.reason));
+
+    for (const { session, reason } of expired) await this.close(session.sessionId, reason);
+  }
+
+  async closeAll(reason: McpSessionCloseReason = 'shutdown'): Promise<void> {
+    for (const sessionId of [...this.sessions.keys()]) await this.close(sessionId, reason);
+  }
+
+  snapshot(): McpSessionSnapshot {
+    const sessions = [...this.sessions.values()];
+    const reservations = [...this.initializeReservations.values()];
+    const activePosts = sessions.reduce((count, session) => count + session.inFlightPosts, 0) + reservations.length;
+    const activeStreams = sessions.reduce((count, session) => count + session.inFlightGets, 0);
+    const evictable = sessions.filter((session) => session.inFlightPosts === 0).length;
+    const reserved = reservations.length;
+    const protectedCount = sessions.length - evictable + reserved;
+    const capacityAvailable = Math.max(0, this.maximumSessions - sessions.length - reserved);
+    const streamOpenedAt = sessions
+      .filter((session) => session.inFlightGets > 0 && session.streamOpenedAt !== undefined)
+      .map((session) => session.streamOpenedAt!);
+    const oldestStreamAgeMs = streamOpenedAt.length === 0 ? 0 : Math.max(0, this.now() - Math.min(...streamOpenedAt));
+    const postOpenedAt = sessions
+      .filter((session) => session.inFlightPosts > 0 && session.postOpenedAt !== undefined)
+      .map((session) => session.postOpenedAt!)
+      .concat(reservations.map((reservation) => reservation.createdAt));
+    const oldestPostAgeMs = postOpenedAt.length === 0 ? 0 : Math.max(0, this.now() - Math.min(...postOpenedAt));
+    const admissionMode = capacityAvailable > 0 ? 'immediate' : evictable > 0 ? 'eviction' : 'blocked';
+    const acceptingNewSessions = admissionMode !== 'blocked';
+    return {
+      active: sessions.length,
+      maximum: this.maximumSessions,
+      capacityAvailable,
+      utilization: this.maximumSessions === 0 ? 1 : (sessions.length + reserved) / this.maximumSessions,
+      admissionMode,
+      acceptingNewSessions,
+      evictable,
+      protected: protectedCount,
+      activePosts,
+      activeStreams,
+      oldestStreamAgeMs,
+      oldestPostAgeMs,
+      recoveryRecommended: !acceptingNewSessions && oldestPostAgeMs >= this.activePostStallMs,
+      closed: { ...this.closeCounters },
+    };
+  }
+
+  private principalSessionCount(principalId: string): number {
+    return [...this.sessions.values()].filter((session) => session.principalId === principalId).length;
+  }
+
+  private principalReservationCount(principalId: string): number {
+    return [...this.initializeReservations.values()].filter((reservation) => reservation.principalId === principalId).length;
+  }
+
+  private async withAdmissionLock<T>(operation: () => Promise<T>): Promise<T> {
+    const previous = this.admissionQueue;
+    let release!: () => void;
+    this.admissionQueue = new Promise<void>((resolve) => { release = resolve; });
+    await previous;
+    try {
+      return await operation();
+    } finally {
+      release();
+    }
+  }
+
+  private safeCandidates(
+    predicate: (session: ManagedMcpSession<TTransport, TContext>) => boolean = () => true,
+  ): ManagedMcpSession<TTransport, TContext>[] {
+    return [...this.sessions.values()]
+      .filter((session) => session.inFlightPosts === 0 && predicate(session))
+      .sort((left, right) => {
+        const leftAge = left.streamOpenedAt ?? left.lastActivityAt;
+        const rightAge = right.streamOpenedAt ?? right.lastActivityAt;
+        return leftAge - rightAge || left.createdAt - right.createdAt || left.sessionId.localeCompare(right.sessionId);
+      });
+  }
+
+  private incrementCloseCounter(reason: McpSessionCloseReason): void {
+    const key = counterForReason(reason);
+    this.closeCounters[key] += 1;
+  }
+}

package/adapters/mcp/transports/stdio.ts

@@ -0,0 +1,8 @@
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { createForgeMcpServer, type McpServerOptions } from '../server';
+
+export async function startMcpStdio(opts: McpServerOptions): Promise<void> {
+  const server = createForgeMcpServer(opts);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/adapters/mcp/tunnels/openai-secure-tunnel.ts

@@ -0,0 +1,139 @@
+import { readFileSync } from 'fs';
+import { credentialReference } from '../../../packages/kernel/identity/api/index';
+
+export const OPENAI_SECURE_TUNNEL_PLATFORM = 'openai-secure-tunnel' as const;
+
+export interface OpenAiSecureTunnelRuntimeConfig {
+  alias: string;
+  tunnelId: string;
+  mcpServerUrl: string;
+  runtimeApiKeyRef?: string;
+  profile?: string;
+  profileDir?: string;
+  adminProfile?: string;
+}
+
+export interface OpenAiSecureTunnelRuntimeStatusPayload {
+  process_running?: boolean;
+  healthy?: boolean;
+  ready?: boolean;
+  tunnel_id?: string;
+  profile_path?: string;
+  runtime_state?: string;
+  error?: string;
+}
+
+export interface OpenAiSecureTunnelRuntimeObservation {
+  ok: boolean;
+  running: boolean;
+  healthy: boolean;
+  ready: boolean;
+  tunnelMatches: boolean;
+  endpointMatches: boolean;
+  alias: string;
+  tunnelId: string;
+  observedTunnelId?: string;
+  detail: string;
+  profilePath?: string;
+}
+
+export function isOpenAiTunnelId(value: string): boolean {
+  return /^tunnel_[0-9a-f]{32}$/.test(value);
+}
+
+export function isOpenAiTunnelAlias(value: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(value);
+}
+
+export function isOpenAiRuntimeApiKeyRef(value: string): boolean {
+  if (/^env:[A-Za-z_][A-Za-z0-9_]*$/.test(value)) return true;
+  return /^file:\//.test(value);
+}
+
+export function tunnelRuntimeProfileTargetsEndpoint(profilePath: string | undefined, endpoint: string): boolean {
+  if (!profilePath) return false;
+  try { return readFileSync(profilePath, 'utf8').includes(endpoint); } catch { return false; }
+}
+
+export function openAiSecureTunnelStatusArgs(
+  alias: string,
+  options: Pick<OpenAiSecureTunnelRuntimeConfig, 'adminProfile'> = {},
+): string[] {
+  if (!isOpenAiTunnelAlias(alias)) throw new Error('OPENAI_TUNNEL_ALIAS_INVALID');
+  const args = ['runtimes', 'status', alias, '--json'];
+  if (options.adminProfile?.trim()) args.push('--admin-profile', options.adminProfile.trim());
+  return args;
+}
+
+export function openAiSecureTunnelConnectArgs(config: OpenAiSecureTunnelRuntimeConfig): string[] {
+  if (!isOpenAiTunnelAlias(config.alias)) throw new Error('OPENAI_TUNNEL_ALIAS_INVALID');
+  if (!isOpenAiTunnelId(config.tunnelId)) throw new Error('OPENAI_TUNNEL_ID_INVALID');
+  if (!config.runtimeApiKeyRef || !isOpenAiRuntimeApiKeyRef(config.runtimeApiKeyRef)) {
+    throw new Error('OPENAI_TUNNEL_RUNTIME_API_KEY_REF_REQUIRED');
+  }
+  // Kernel receives only a reference shape; tunnel-client remains owner of the secret.
+  credentialReference(config.runtimeApiKeyRef, OPENAI_SECURE_TUNNEL_PLATFORM);
+  const endpoint = new URL(config.mcpServerUrl);
+  if (endpoint.protocol !== 'http:' || !['127.0.0.1', 'localhost', '::1'].includes(endpoint.hostname)) {
+    throw new Error('OPENAI_TUNNEL_MCP_SERVER_LOOPBACK_REQUIRED');
+  }
+  const args = [
+    'runtimes', 'connect',
+    '--alias', config.alias,
+    '--tunnel-id', config.tunnelId,
+    '--runtime-api-key', config.runtimeApiKeyRef,
+    '--mcp-server-url', config.mcpServerUrl,
+  ];
+  if (config.adminProfile) args.push('--admin-profile', config.adminProfile);
+  if (config.profile) args.push('--profile', config.profile);
+  if (config.profileDir) args.push('--profile-dir', config.profileDir);
+  return args;
+}
+
+export function parseOpenAiSecureTunnelRuntimeStatus(
+  stdout: string,
+  expected: Pick<OpenAiSecureTunnelRuntimeConfig, 'alias' | 'tunnelId' | 'mcpServerUrl'>,
+): OpenAiSecureTunnelRuntimeObservation {
+  let value: OpenAiSecureTunnelRuntimeStatusPayload;
+  try {
+    value = JSON.parse(stdout || '{}') as OpenAiSecureTunnelRuntimeStatusPayload;
+  } catch {
+    return {
+      ok: false,
+      running: false,
+      healthy: false,
+      ready: false,
+      tunnelMatches: false,
+      endpointMatches: false,
+      alias: expected.alias,
+      tunnelId: expected.tunnelId,
+      detail: 'OpenAI tunnel runtime status was not valid JSON',
+    };
+  }
+  const running = value.process_running === true;
+  const healthy = value.healthy === true;
+  const ready = value.ready === true;
+  const tunnelMatches = value.tunnel_id === expected.tunnelId;
+  const endpointMatches = tunnelRuntimeProfileTargetsEndpoint(value.profile_path, expected.mcpServerUrl);
+  const ok = running && healthy && ready && tunnelMatches && endpointMatches;
+  const mismatches: string[] = [];
+  if (!tunnelMatches && value.tunnel_id) mismatches.push(`tunnel id mismatch (${value.tunnel_id})`);
+  if (!endpointMatches && value.profile_path) mismatches.push('runtime profile targets a different MCP endpoint');
+  if (!running) mismatches.push(`runtime is ${value.runtime_state ?? 'not running'}`);
+  if (running && !healthy) mismatches.push('runtime is not healthy');
+  if (running && !ready) mismatches.push('runtime is not ready');
+  if (value.error) mismatches.push(value.error);
+  return {
+    ok,
+    running,
+    healthy,
+    ready,
+    tunnelMatches,
+    endpointMatches,
+    alias: expected.alias,
+    tunnelId: expected.tunnelId,
+    ...(value.tunnel_id ? { observedTunnelId: value.tunnel_id } : {}),
+    detail: ok ? `managed runtime ${expected.alias} is ready for ${expected.tunnelId}` : (mismatches.join('; ') || 'OpenAI tunnel runtime is not ready'),
+    ...(value.profile_path ? { profilePath: value.profile_path } : {}),
+  };
+}