@evalops/maestro 0.10.8 → 0.10.10

package/dist/remote-runner/client.js

@@ -0,0 +1,633 @@
+import { randomUUID } from "node:crypto";
+import { getEnvValue, normalizeBaseUrl, postPlatformConnect, resolvePlatformServiceConfig, trimString, } from "../platform/client.js";
+import { PLATFORM_CONNECT_METHODS, PLATFORM_CONNECT_SERVICES, platformConnectMethodPath, platformConnectServicePath, } from "../platform/core-services.js";
+import { fetchDownstream } from "../utils/downstream-http.js";
+export const DEFAULT_REMOTE_RUNNER_BASE_URL = "https://runner.evalops.dev";
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_ATTEMPTS = 2;
+export const DEFAULT_REMOTE_RUNNER_WAIT_TIMEOUT_MS = 5 * 60 * 1000;
+export const DEFAULT_REMOTE_RUNNER_WAIT_POLL_INTERVAL_MS = 5_000;
+const CREATE_RUNNER_SESSION_PATH = platformConnectMethodPath(PLATFORM_CONNECT_METHODS.remoteRunner.createRunnerSession);
+const GET_RUNNER_SESSION_PATH = platformConnectMethodPath(PLATFORM_CONNECT_METHODS.remoteRunner.getRunnerSession);
+const LIST_RUNNER_SESSIONS_PATH = platformConnectMethodPath(PLATFORM_CONNECT_METHODS.remoteRunner.listRunnerSessions);
+const STOP_RUNNER_SESSION_PATH = platformConnectMethodPath(PLATFORM_CONNECT_METHODS.remoteRunner.stopRunnerSession);
+const EXTEND_RUNNER_SESSION_PATH = platformConnectMethodPath(PLATFORM_CONNECT_METHODS.remoteRunner.extendRunnerSession);
+const MINT_ATTACH_TOKEN_PATH = platformConnectMethodPath(PLATFORM_CONNECT_METHODS.remoteRunner.mintAttachToken);
+const REVOKE_ATTACH_TOKEN_PATH = platformConnectMethodPath(PLATFORM_CONNECT_METHODS.remoteRunner.revokeAttachToken);
+const LIST_RUNNER_SESSION_EVENTS_PATH = platformConnectMethodPath(PLATFORM_CONNECT_METHODS.remoteRunner.listRunnerSessionEvents);
+const GET_REMOTE_RUNNER_STATUS_PATH = platformConnectMethodPath(PLATFORM_CONNECT_METHODS.remoteRunner.getStatus);
+export const RUNNER_SESSION_STATES = {
+    UNSPECIFIED: "RUNNER_SESSION_STATE_UNSPECIFIED",
+    REQUESTED: "RUNNER_SESSION_STATE_REQUESTED",
+    PROVISIONING: "RUNNER_SESSION_STATE_PROVISIONING",
+    RUNNING: "RUNNER_SESSION_STATE_RUNNING",
+    IDLE: "RUNNER_SESSION_STATE_IDLE",
+    STOPPING: "RUNNER_SESSION_STATE_STOPPING",
+    STOPPED: "RUNNER_SESSION_STATE_STOPPED",
+    EXPIRED: "RUNNER_SESSION_STATE_EXPIRED",
+    FAILED: "RUNNER_SESSION_STATE_FAILED",
+    LOST: "RUNNER_SESSION_STATE_LOST",
+};
+export const RUNNER_ATTACH_ROLES = {
+    UNSPECIFIED: "RUNNER_ATTACH_ROLE_UNSPECIFIED",
+    VIEWER: "RUNNER_ATTACH_ROLE_VIEWER",
+    CONTROLLER: "RUNNER_ATTACH_ROLE_CONTROLLER",
+    ADMIN: "RUNNER_ATTACH_ROLE_ADMIN",
+};
+const REMOTE_RUNNER_BASE_URL_ENV_VARS = [
+    "MAESTRO_REMOTE_RUNNER_URL",
+    "REMOTE_RUNNER_SERVICE_URL",
+    "EVALOPS_REMOTE_RUNNER_URL",
+];
+const REMOTE_RUNNER_TOKEN_ENV_VARS = [
+    "MAESTRO_REMOTE_RUNNER_TOKEN",
+    "REMOTE_RUNNER_SERVICE_TOKEN",
+    "MAESTRO_EVALOPS_ACCESS_TOKEN",
+    "EVALOPS_TOKEN",
+];
+const REMOTE_RUNNER_ORGANIZATION_ENV_VARS = [
+    "MAESTRO_REMOTE_RUNNER_ORG_ID",
+    "REMOTE_RUNNER_ORGANIZATION_ID",
+    "MAESTRO_EVALOPS_ORG_ID",
+    "EVALOPS_ORGANIZATION_ID",
+    "MAESTRO_ENTERPRISE_ORG_ID",
+];
+const REMOTE_RUNNER_WORKSPACE_ENV_VARS = [
+    "MAESTRO_REMOTE_RUNNER_WORKSPACE_ID",
+    "REMOTE_RUNNER_WORKSPACE_ID",
+    "MAESTRO_WORKSPACE_ID",
+    "EVALOPS_WORKSPACE_ID",
+];
+const REMOTE_RUNNER_TIMEOUT_ENV_VARS = [
+    "MAESTRO_REMOTE_RUNNER_TIMEOUT_MS",
+    "REMOTE_RUNNER_SERVICE_TIMEOUT_MS",
+];
+const REMOTE_RUNNER_MAX_ATTEMPTS_ENV_VARS = [
+    "MAESTRO_REMOTE_RUNNER_MAX_ATTEMPTS",
+    "REMOTE_RUNNER_SERVICE_MAX_ATTEMPTS",
+];
+const REMOTE_RUNNER_BASE_URL_SUFFIXES = [
+    CREATE_RUNNER_SESSION_PATH,
+    GET_RUNNER_SESSION_PATH,
+    LIST_RUNNER_SESSIONS_PATH,
+    STOP_RUNNER_SESSION_PATH,
+    EXTEND_RUNNER_SESSION_PATH,
+    MINT_ATTACH_TOKEN_PATH,
+    REVOKE_ATTACH_TOKEN_PATH,
+    LIST_RUNNER_SESSION_EVENTS_PATH,
+    GET_REMOTE_RUNNER_STATUS_PATH,
+    platformConnectServicePath(PLATFORM_CONNECT_SERVICES.remoteRunner),
+    "/v1/runner-sessions",
+    "/v1/runner-sessions/",
+];
+export class WaitForRunnerSessionReadyError extends Error {
+    constructor(input) {
+        super(input.message);
+        this.name = "WaitForRunnerSessionReadyError";
+        this.code = input.code;
+        this.elapsedMs = input.elapsedMs;
+        this.attempts = input.attempts;
+        this.session = input.session;
+    }
+}
+function runnerSessionReadyRequestOptions(options) {
+    return {
+        baseUrl: options.baseUrl,
+        token: options.token,
+        organizationId: options.organizationId,
+        workspaceId: options.workspaceId,
+        maxAttempts: options.maxAttempts,
+        timeoutMs: options.requestTimeoutMs,
+    };
+}
+function firstString(record, ...names) {
+    for (const name of names) {
+        const value = record?.[name];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function firstNumber(record, ...names) {
+    for (const name of names) {
+        const value = record?.[name];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return value;
+        }
+        if (typeof value === "string") {
+            const parsed = Number(value);
+            if (Number.isFinite(parsed)) {
+                return parsed;
+            }
+        }
+    }
+    return undefined;
+}
+function firstRecord(record, ...names) {
+    for (const name of names) {
+        const value = record?.[name];
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function firstArray(record, ...names) {
+    for (const name of names) {
+        const value = record?.[name];
+        if (Array.isArray(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function stripUndefinedValues(body) {
+    return Object.fromEntries(Object.entries(body).filter((entry) => {
+        return entry[1] !== undefined;
+    }));
+}
+function normalizeRunnerSession(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value;
+    const id = firstString(record, "id");
+    if (!id) {
+        return undefined;
+    }
+    return {
+        id,
+        organizationId: firstString(record, "organizationId", "organization_id"),
+        workspaceId: firstString(record, "workspaceId", "workspace_id"),
+        userId: firstString(record, "userId", "user_id"),
+        agentRunId: firstString(record, "agentRunId", "agent_run_id"),
+        maestroSessionId: firstString(record, "maestroSessionId", "maestro_session_id"),
+        state: firstString(record, "state"),
+        runnerProfile: firstString(record, "runnerProfile", "runner_profile"),
+        runnerImage: firstString(record, "runnerImage", "runner_image"),
+        workspaceSource: firstString(record, "workspaceSource", "workspace_source"),
+        repoUrl: firstString(record, "repoUrl", "repo_url"),
+        branch: firstString(record, "branch"),
+        model: firstString(record, "model"),
+        ownerInstanceId: firstString(record, "ownerInstanceId", "owner_instance_id"),
+        runnerPodNamespace: firstString(record, "runnerPodNamespace", "runner_pod_namespace"),
+        runnerPodName: firstString(record, "runnerPodName", "runner_pod_name"),
+        runnerServiceName: firstString(record, "runnerServiceName", "runner_service_name"),
+        createdAt: firstString(record, "createdAt", "created_at"),
+        startedAt: firstString(record, "startedAt", "started_at"),
+        expiresAt: firstString(record, "expiresAt", "expires_at"),
+        idleExpiresAt: firstString(record, "idleExpiresAt", "idle_expires_at"),
+        stoppedAt: firstString(record, "stoppedAt", "stopped_at"),
+        stopReason: firstString(record, "stopReason", "stop_reason"),
+        lastHeartbeatAt: firstString(record, "lastHeartbeatAt", "last_heartbeat_at"),
+        usedRunnerSeconds: firstNumber(record, "usedRunnerSeconds", "used_runner_seconds"),
+        usedIdleSeconds: firstNumber(record, "usedIdleSeconds", "used_idle_seconds"),
+        estimatedCostMicros: firstNumber(record, "estimatedCostMicros", "estimated_cost_micros"),
+        metadata: firstRecord(record, "metadata"),
+    };
+}
+function normalizeRunnerSessionEvent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value;
+    return {
+        id: firstString(record, "id"),
+        sessionId: firstString(record, "sessionId", "session_id"),
+        sequence: firstNumber(record, "sequence"),
+        eventType: firstString(record, "eventType", "event_type"),
+        occurredAt: firstString(record, "occurredAt", "occurred_at"),
+        payload: firstRecord(record, "payload"),
+    };
+}
+function normalizeRunnerAttachToken(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value;
+    const id = firstString(record, "id");
+    if (!id) {
+        return undefined;
+    }
+    return {
+        id,
+        sessionId: firstString(record, "sessionId", "session_id"),
+        subjectId: firstString(record, "subjectId", "subject_id"),
+        roles: firstArray(record, "roles")?.filter((value) => typeof value === "string"),
+        createdAt: firstString(record, "createdAt", "created_at"),
+        expiresAt: firstString(record, "expiresAt", "expires_at"),
+        revokedAt: firstString(record, "revokedAt", "revoked_at"),
+    };
+}
+function requireSession(payload, serviceName) {
+    const session = normalizeRunnerSession(payload.session);
+    if (!session) {
+        throw new Error(`${serviceName} returned no runner session`);
+    }
+    return session;
+}
+function requireAttachToken(payload, serviceName) {
+    const token = normalizeRunnerAttachToken(payload.token);
+    if (!token) {
+        throw new Error(`${serviceName} returned no attach token`);
+    }
+    return token;
+}
+function ensurePositiveMinutes(value, field, max = 1440) {
+    if (!Number.isInteger(value) || value < 1 || value > max) {
+        throw new Error(`${field} must be an integer between 1 and ${max}`);
+    }
+    return value;
+}
+function ensureNonNegativeMinutes(value, field, max = 1440) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Number.isInteger(value) || value < 0 || value > max) {
+        throw new Error(`${field} must be an integer between 0 and ${max}`);
+    }
+    return value;
+}
+function normalizeRole(role) {
+    const normalized = role
+        .trim()
+        .toUpperCase()
+        .replace(/^RUNNER_ATTACH_ROLE_/u, "");
+    const matched = RUNNER_ATTACH_ROLES[normalized];
+    if (!matched || matched === RUNNER_ATTACH_ROLES.UNSPECIFIED) {
+        throw new Error(`Unknown runner attach role: ${role}`);
+    }
+    return matched;
+}
+function normalizeState(state) {
+    const normalized = state
+        .trim()
+        .toUpperCase()
+        .replace(/^RUNNER_SESSION_STATE_/u, "");
+    const matched = RUNNER_SESSION_STATES[normalized];
+    if (!matched || matched === RUNNER_SESSION_STATES.UNSPECIFIED) {
+        throw new Error(`Unknown runner session state: ${state}`);
+    }
+    return matched;
+}
+function stateMatches(state, expected) {
+    if (!state) {
+        return false;
+    }
+    try {
+        return expected.includes(normalizeState(state));
+    }
+    catch {
+        return false;
+    }
+}
+function describeState(state) {
+    return (state
+        ?.replace(/^RUNNER_SESSION_STATE_/u, "")
+        .toLowerCase()
+        .replaceAll("_", "-") ?? "unknown");
+}
+function waitDelay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function normalizeConfig(config, overrides) {
+    const organizationId = trimString(overrides.organizationId ?? config.organizationId);
+    const token = trimString(overrides.token ?? config.token);
+    if (!organizationId || !token) {
+        return null;
+    }
+    const explicitBaseUrl = trimString(overrides.baseUrl ?? config.baseUrl);
+    const baseUrl = normalizeBaseUrl(explicitBaseUrl ?? DEFAULT_REMOTE_RUNNER_BASE_URL, REMOTE_RUNNER_BASE_URL_SUFFIXES);
+    return {
+        ...config,
+        baseUrl,
+        token,
+        organizationId,
+        workspaceId: trimString(overrides.workspaceId ?? config.workspaceId),
+        timeoutMs: overrides.timeoutMs ?? config.timeoutMs,
+        maxAttempts: overrides.maxAttempts ?? config.maxAttempts,
+    };
+}
+export async function resolveRemoteRunnerConfig(overrides = {}) {
+    const config = await resolvePlatformServiceConfig({
+        baseUrlEnvVars: REMOTE_RUNNER_BASE_URL_ENV_VARS,
+        tokenEnvVars: REMOTE_RUNNER_TOKEN_ENV_VARS,
+        organizationEnvVars: REMOTE_RUNNER_ORGANIZATION_ENV_VARS,
+        workspaceEnvVars: REMOTE_RUNNER_WORKSPACE_ENV_VARS,
+        timeoutEnvVars: REMOTE_RUNNER_TIMEOUT_ENV_VARS,
+        maxAttemptsEnvVars: REMOTE_RUNNER_MAX_ATTEMPTS_ENV_VARS,
+        baseUrlSuffixes: REMOTE_RUNNER_BASE_URL_SUFFIXES,
+        defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+        defaultMaxAttempts: DEFAULT_MAX_ATTEMPTS,
+        requireBaseUrl: false,
+        requireOrganizationId: true,
+        requireToken: true,
+    });
+    if (!config) {
+        return null;
+    }
+    return normalizeConfig(config, overrides);
+}
+export function hasRemoteRunnerDestination() {
+    const organizationId = getEnvValue(REMOTE_RUNNER_ORGANIZATION_ENV_VARS);
+    const token = getEnvValue(REMOTE_RUNNER_TOKEN_ENV_VARS);
+    return Boolean(organizationId && token);
+}
+export function remoteRunnerGatewayBaseUrl(config, sessionId) {
+    return `${config.baseUrl}/v1/runner-sessions/${encodeURIComponent(sessionId)}/headless`;
+}
+async function postRemoteRunner(config, path, body, normalize) {
+    const response = await postPlatformConnect(config, path, stripUndefinedValues(body), {
+        serviceName: "remote runner service",
+        failureMode: "required",
+        timeoutMs: config.timeoutMs,
+        maxAttempts: config.maxAttempts,
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`remote runner service returned ${response.status}: ${text || response.statusText}`);
+    }
+    const text = await response.text();
+    if (!text.trim()) {
+        throw new Error("remote runner service returned empty response");
+    }
+    return normalize(JSON.parse(text));
+}
+async function requireRemoteRunnerConfig(overrides) {
+    const config = await resolveRemoteRunnerConfig(overrides);
+    if (!config) {
+        throw new Error("Remote runner requires EvalOps organization and access token. Set MAESTRO_REMOTE_RUNNER_ORG_ID/MAESTRO_EVALOPS_ORG_ID and MAESTRO_REMOTE_RUNNER_TOKEN/MAESTRO_EVALOPS_ACCESS_TOKEN, or run EvalOps login.");
+    }
+    return config;
+}
+export async function createRunnerSession(input, options = {}) {
+    const config = await requireRemoteRunnerConfig(options);
+    const workspaceId = trimString(input.workspaceId ?? config.workspaceId);
+    if (!workspaceId) {
+        throw new Error("Remote runner start requires a workspace id. Pass --workspace or set MAESTRO_REMOTE_RUNNER_WORKSPACE_ID.");
+    }
+    const ttlMinutes = ensurePositiveMinutes(input.ttlMinutes, "ttlMinutes");
+    const idleTtlMinutes = ensureNonNegativeMinutes(input.idleTtlMinutes, "idleTtlMinutes");
+    return postRemoteRunner(config, CREATE_RUNNER_SESSION_PATH, {
+        organizationId: config.organizationId,
+        workspaceId,
+        userId: trimString(input.userId),
+        agentRunId: trimString(input.agentRunId),
+        maestroSessionId: trimString(input.maestroSessionId),
+        idempotencyKey: trimString(input.idempotencyKey) ?? randomUUID(),
+        runnerProfile: trimString(input.runnerProfile),
+        runnerImage: trimString(input.runnerImage),
+        workspaceSource: trimString(input.workspaceSource),
+        repoUrl: trimString(input.repoUrl),
+        branch: trimString(input.branch),
+        model: trimString(input.model),
+        ttlMinutes,
+        idleTtlMinutes,
+        metadata: input.metadata,
+    }, (payload) => ({
+        session: requireSession(payload, "remote runner service"),
+        events: firstArray(payload, "events")
+            ?.map(normalizeRunnerSessionEvent)
+            .filter((event) => Boolean(event)) ?? [],
+        replayed: payload.replayed === true,
+    }));
+}
+export async function getRunnerSession(sessionId, options = {}) {
+    const config = await requireRemoteRunnerConfig(options);
+    return postRemoteRunner(config, GET_RUNNER_SESSION_PATH, { sessionId: trimString(sessionId) }, (payload) => requireSession(payload, "remote runner service"));
+}
+export async function listRunnerSessions(input = {}, options = {}) {
+    const config = await requireRemoteRunnerConfig(options);
+    const workspaceId = trimString(input.workspaceId ?? config.workspaceId);
+    if (!workspaceId) {
+        throw new Error("Remote runner list requires a workspace id. Pass --workspace or set MAESTRO_REMOTE_RUNNER_WORKSPACE_ID.");
+    }
+    return postRemoteRunner(config, LIST_RUNNER_SESSIONS_PATH, {
+        organizationId: config.organizationId,
+        workspaceId,
+        state: input.state ? normalizeState(input.state) : undefined,
+        limit: input.limit,
+        offset: input.offset,
+    }, (payload) => ({
+        sessions: firstArray(payload, "sessions")
+            ?.map(normalizeRunnerSession)
+            .filter((session) => Boolean(session)) ??
+            [],
+        nextOffset: firstNumber(payload, "nextOffset", "next_offset"),
+    }));
+}
+export async function stopRunnerSession(sessionId, reason, options = {}) {
+    const config = await requireRemoteRunnerConfig(options);
+    return postRemoteRunner(config, STOP_RUNNER_SESSION_PATH, { sessionId: trimString(sessionId), reason: trimString(reason) }, (payload) => ({
+        session: requireSession(payload, "remote runner service"),
+        event: normalizeRunnerSessionEvent(payload.event),
+    }));
+}
+export async function extendRunnerSession(input, options = {}) {
+    const config = await requireRemoteRunnerConfig(options);
+    return postRemoteRunner(config, EXTEND_RUNNER_SESSION_PATH, {
+        sessionId: trimString(input.sessionId),
+        additionalMinutes: ensurePositiveMinutes(input.additionalMinutes, "additionalMinutes"),
+        additionalIdleMinutes: ensureNonNegativeMinutes(input.additionalIdleMinutes, "additionalIdleMinutes"),
+        reason: trimString(input.reason),
+    }, (payload) => ({
+        session: requireSession(payload, "remote runner service"),
+        event: normalizeRunnerSessionEvent(payload.event),
+    }));
+}
+export async function mintRunnerAttachToken(input, options = {}) {
+    const config = await requireRemoteRunnerConfig(options);
+    const sessionId = trimString(input.sessionId);
+    if (!sessionId) {
+        throw new Error("Attach token requires a runner session id");
+    }
+    const roles = (input.roles?.length ? input.roles : [RUNNER_ATTACH_ROLES.CONTROLLER]).map(normalizeRole);
+    const ttlMinutes = ensureNonNegativeMinutes(input.ttlMinutes ?? 30, "ttlMinutes", 60);
+    const result = await postRemoteRunner(config, MINT_ATTACH_TOKEN_PATH, {
+        sessionId,
+        subjectId: trimString(input.subjectId),
+        roles,
+        ttlMinutes,
+    }, (payload) => {
+        const tokenSecret = firstString(payload, "tokenSecret", "token_secret");
+        if (!tokenSecret) {
+            throw new Error("remote runner service returned no attach token secret");
+        }
+        return {
+            token: requireAttachToken(payload, "remote runner service"),
+            tokenSecret,
+        };
+    });
+    return {
+        ...result,
+        gatewayBaseUrl: remoteRunnerGatewayBaseUrl(config, sessionId),
+    };
+}
+export async function revokeRunnerAttachToken(input, options = {}) {
+    const config = await requireRemoteRunnerConfig(options);
+    return postRemoteRunner(config, REVOKE_ATTACH_TOKEN_PATH, {
+        sessionId: trimString(input.sessionId),
+        tokenId: trimString(input.tokenId),
+    }, (payload) => ({
+        token: requireAttachToken(payload, "remote runner service"),
+        event: normalizeRunnerSessionEvent(payload.event),
+    }));
+}
+export async function listRunnerSessionEvents(input, options = {}) {
+    const config = await requireRemoteRunnerConfig(options);
+    return postRemoteRunner(config, LIST_RUNNER_SESSION_EVENTS_PATH, {
+        sessionId: trimString(input.sessionId),
+        afterSequence: input.afterSequence,
+        limit: input.limit,
+    }, (payload) => ({
+        events: firstArray(payload, "events")
+            ?.map(normalizeRunnerSessionEvent)
+            .filter((event) => Boolean(event)) ?? [],
+        nextSequence: firstNumber(payload, "nextSequence", "next_sequence"),
+    }));
+}
+export async function getRemoteRunnerStatus(workspaceId, options = {}) {
+    const config = await requireRemoteRunnerConfig(options);
+    const resolvedWorkspaceId = trimString(workspaceId ?? config.workspaceId);
+    if (!resolvedWorkspaceId) {
+        throw new Error("Remote runner status requires a workspace id. Pass --workspace or set MAESTRO_REMOTE_RUNNER_WORKSPACE_ID.");
+    }
+    return postRemoteRunner(config, GET_REMOTE_RUNNER_STATUS_PATH, {
+        workspaceId: resolvedWorkspaceId,
+    }, (payload) => ({
+        service: firstString(payload, "service"),
+        workspaceId: firstString(payload, "workspaceId", "workspace_id"),
+        downstreamPolicy: firstString(payload, "downstreamPolicy", "downstream_policy"),
+    }));
+}
+export async function waitForRunnerSessionReady(sessionId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_REMOTE_RUNNER_WAIT_TIMEOUT_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_REMOTE_RUNNER_WAIT_POLL_INTERVAL_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 1) {
+        throw new Error("Remote runner wait timeout must be at least 1ms");
+    }
+    if (!Number.isFinite(pollIntervalMs) || pollIntervalMs < 0) {
+        throw new Error("Remote runner poll interval must be 0ms or greater");
+    }
+    const readyStates = [
+        RUNNER_SESSION_STATES.RUNNING,
+        RUNNER_SESSION_STATES.IDLE,
+    ];
+    const terminalStates = [
+        RUNNER_SESSION_STATES.STOPPED,
+        RUNNER_SESSION_STATES.EXPIRED,
+        RUNNER_SESSION_STATES.FAILED,
+        RUNNER_SESSION_STATES.LOST,
+    ];
+    const startedAt = Date.now();
+    let attempts = 0;
+    let lastSession;
+    const requestOptions = runnerSessionReadyRequestOptions(options);
+    while (true) {
+        attempts += 1;
+        lastSession = await getRunnerSession(sessionId, requestOptions);
+        const elapsedMs = Date.now() - startedAt;
+        if (stateMatches(lastSession.state, readyStates)) {
+            return {
+                session: lastSession,
+                attempts,
+                elapsedMs,
+            };
+        }
+        if (stateMatches(lastSession.state, terminalStates)) {
+            const stopReason = lastSession.stopReason?.trim();
+            throw new WaitForRunnerSessionReadyError({
+                message: stopReason
+                    ? `Remote runner session ${sessionId} entered terminal state ${describeState(lastSession.state)}: ${stopReason}`
+                    : `Remote runner session ${sessionId} entered terminal state ${describeState(lastSession.state)}`,
+                code: "terminal_state",
+                elapsedMs,
+                attempts,
+                session: lastSession,
+            });
+        }
+        if (elapsedMs >= timeoutMs) {
+            throw new WaitForRunnerSessionReadyError({
+                message: `Timed out after ${timeoutMs}ms waiting for remote runner session ${sessionId} to become ready (last state: ${describeState(lastSession.state)})`,
+                code: "timeout",
+                elapsedMs,
+                attempts,
+                session: lastSession,
+            });
+        }
+        const remainingMs = timeoutMs - elapsedMs;
+        const sleepMs = Math.min(pollIntervalMs, remainingMs);
+        if (sleepMs > 0) {
+            await waitDelay(sleepMs);
+        }
+    }
+}
+export async function verifyRunnerHeadlessAttach(input) {
+    const headers = {
+        Authorization: `Bearer ${input.tokenSecret}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "X-EvalOps-Runner-Attach-Token-Id": input.tokenId,
+    };
+    const body = {
+        sessionId: input.sessionId,
+        protocolVersion: input.protocolVersion,
+        clientInfo: {
+            name: "maestro-remote-cli",
+            version: input.clientVersion,
+        },
+        role: "controller",
+        takeControl: input.takeControl ?? false,
+        optOutNotifications: ["heartbeat"],
+        capabilities: {
+            serverRequests: ["approval", "user_input", "tool_retry"],
+            utilityOperations: [
+                "command_exec",
+                "file_search",
+                "file_read",
+                "file_watch",
+            ],
+        },
+    };
+    const response = await fetchDownstream(`${input.gatewayBaseUrl}/api/headless/connections`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    }, {
+        serviceName: "remote runner headless gateway",
+        failureMode: "required",
+        timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        maxAttempts: 1,
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`remote runner headless gateway returned ${response.status}: ${text || response.statusText}`);
+    }
+    const payload = text.trim()
+        ? JSON.parse(text)
+        : {};
+    const connectionId = firstString(payload, "connection_id", "connectionId");
+    const runtimeSessionId = firstString(payload, "session_id", "sessionId");
+    if (connectionId || runtimeSessionId) {
+        void fetchDownstream(`${input.gatewayBaseUrl}/api/headless/sessions/${encodeURIComponent(runtimeSessionId ?? input.sessionId)}/disconnect`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ connectionId }),
+        }, {
+            serviceName: "remote runner headless gateway",
+            failureMode: "required",
+            timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            maxAttempts: 1,
+        }).catch(() => undefined);
+    }
+    return {
+        sessionId: runtimeSessionId,
+        connectionId,
+        heartbeatIntervalMs: firstNumber(payload, "heartbeat_interval_ms", "heartbeatIntervalMs"),
+        role: firstString(payload, "role"),
+    };
+}
+//# sourceMappingURL=client.js.map