@agent-vm/gateway-lifecycle 0.0.115

package/dist/index.d.ts

@@ -0,0 +1,1121 @@
+import { MediatedSecretSpec, SecretResolver } from "@agent-vm/secret-management";
+import { ManagedVmGitReadOnlySshEgress, ManagedVmMount } from "@agent-vm/managed-vm";
+
+//#region src/gateway-runtime-contract.d.ts
+declare const gatewayTypeValues: readonly ["openclaw", "hermes", "worker"];
+type GatewayType = (typeof gatewayTypeValues)[number];
+declare function buildGatewaySessionLabel(projectNamespace: string, zoneId: string): string;
+declare function buildToolSessionLabel(projectNamespace: string, zoneId: string, tcpSlot: number): string;
+//#endregion
+//#region src/audience.d.ts
+declare const vmAudienceValues: readonly ["gateway", "tool-vm", "both"];
+type VmAudience = (typeof vmAudienceValues)[number];
+type RuntimeVmAudience = Exclude<VmAudience, 'both'>;
+interface EgressHostConfig {
+  readonly host: string;
+  readonly audience: VmAudience;
+}
+declare const controllerVmHost = "controller.vm.host";
+declare function targetsAudience(configAudience: VmAudience, runtimeAudience: RuntimeVmAudience): boolean;
+declare function egressHostsForAudience(egressHosts: readonly EgressHostConfig[], runtimeAudience: RuntimeVmAudience): readonly string[];
+declare function gatewayVmAllowedHosts(egressHosts: readonly EgressHostConfig[]): readonly string[];
+declare function workerVmAllowedHosts(egressHosts: readonly EgressHostConfig[]): readonly string[];
+//#endregion
+//#region src/gateway-control-private-environment.d.ts
+declare const GATEWAY_CONTROL_CALLER_CONTEXT_PROOF_KEY_ENV = "AGENT_VM_GATEWAY_CONTROL_CALLER_CONTEXT_PROOF_KEY";
+declare const GATEWAY_CONTROL_CALLER_CONTEXT_AGENT_AUTHORITY_KEYS_ENV = "AGENT_VM_GATEWAY_CONTROL_CALLER_CONTEXT_AGENT_AUTHORITY_KEYS";
+declare const GATEWAY_CONTROL_PRIVATE_ENVIRONMENT_NAMES: readonly ["AGENT_VM_GATEWAY_CONTROL_CALLER_CONTEXT_AGENT_AUTHORITY_KEYS", "AGENT_VM_GATEWAY_CONTROL_CALLER_CONTEXT_PROOF_KEY"];
+type GatewayControlPrivateEnvironmentName = (typeof GATEWAY_CONTROL_PRIVATE_ENVIRONMENT_NAMES)[number];
+//#endregion
+//#region src/gateway-process-spec.d.ts
+type GatewayHealthCheck = {
+  readonly type: 'http';
+  readonly port: number;
+  readonly path: string;
+} | {
+  readonly type: 'command';
+  readonly command: string;
+};
+/**
+ * Everything about the process running inside the VM.
+ * Retained by the running gateway handle for logs, health, restart.
+ */
+interface GatewayProcessSpec {
+  readonly bootstrapCommand: string;
+  readonly startCommand: string;
+  readonly healthCheck: GatewayHealthCheck;
+  readonly serviceHealthCheck?: GatewayHealthCheck | undefined;
+  readonly guestListenPort: number;
+  readonly logPath: string;
+}
+//#endregion
+//#region src/websocket-upgrade-policy.d.ts
+interface WebSocketUpgradeConfig {
+  readonly audience: VmAudience;
+  readonly scheme: 'ws' | 'wss';
+  readonly host: string;
+  readonly port?: number | undefined;
+  readonly path?: string | undefined;
+}
+interface CreateWebSocketUpgradeRequestGuardOptions {
+  readonly rules: readonly WebSocketUpgradeConfig[];
+  readonly runtimeAudience: RuntimeVmAudience;
+}
+declare function websocketUpgradesForAudience(rules: readonly WebSocketUpgradeConfig[] | undefined, runtimeAudience: RuntimeVmAudience): readonly WebSocketUpgradeConfig[];
+declare function createWebSocketUpgradeRequestGuard(options: CreateWebSocketUpgradeRequestGuardOptions): (request: Request) => Promise<Response | void>;
+//#endregion
+//#region src/gateway-vm-spec.d.ts
+/**
+ * Guest workload requirements produced by a gateway lifecycle.
+ *
+ * Image selection, resources, VM construction, and backend translation remain
+ * controller/composition responsibilities.
+ */
+interface GatewayVmRequirements {
+  readonly environment: Record<string, string>;
+  readonly mounts: Record<string, ManagedVmMount>;
+  readonly mediatedSecrets: Record<string, MediatedSecretSpec>;
+  readonly tcpHosts: Record<string, string>;
+  readonly sshEgress?: ManagedVmGitReadOnlySshEgress;
+  readonly allowedHosts: readonly string[];
+  readonly websocketUpgrades?: readonly WebSocketUpgradeConfig[];
+  readonly rootfsMode: 'readonly' | 'memory' | 'cow';
+  readonly runtimeRootfsSize?: string;
+  readonly sessionLabel: string;
+}
+//#endregion
+//#region src/managed-gateway-boot-contract.d.ts
+type ManagedFrameworkKind = 'openclaw' | 'hermes';
+type ManagedFrameworkBootEntry = 'openclaw-gateway' | 'hermes-gateway';
+interface ManagedGatewayLogIdentity {
+  readonly guestPath: string;
+  readonly serviceName: string;
+}
+interface ManagedToolPortalReadinessMetadata {
+  readonly evidencePath: string;
+  readonly kind: 'tool-portal-evidence';
+  readonly socketPath: string;
+}
+interface ManagedFrameworkReadinessMetadata {
+  readonly guestPort: number;
+  readonly kind: 'framework-http';
+  readonly path: string;
+}
+interface ManagedFrameworkIngressMetadata {
+  readonly guestPort: number;
+  readonly kind: 'framework-http';
+}
+interface ManagedToolPortalServiceBootMetadata {
+  readonly bootEntry: 'agent-vm-gateway-runtime';
+  readonly configurationInputPath: string;
+  readonly environmentInputPath: string;
+  readonly logIdentity: ManagedGatewayLogIdentity;
+  readonly readiness: ManagedToolPortalReadinessMetadata;
+  readonly role: 'tool-portal-service';
+}
+interface ManagedFrameworkServiceBootMetadataBase {
+  readonly configurationInputPath: string;
+  readonly environmentInputPath: string;
+  readonly ingress: ManagedFrameworkIngressMetadata;
+  readonly logIdentity: ManagedGatewayLogIdentity;
+  readonly readiness: ManagedFrameworkReadinessMetadata;
+  readonly role: 'framework-service';
+}
+interface ManagedOpenClawServiceBootMetadata extends ManagedFrameworkServiceBootMetadataBase {
+  readonly bootEntry: 'openclaw-gateway';
+  readonly framework: 'openclaw';
+}
+interface ManagedHermesServiceBootMetadata extends ManagedFrameworkServiceBootMetadataBase {
+  readonly bootEntry: 'hermes-gateway';
+  readonly framework: 'hermes';
+}
+type ManagedFrameworkServiceBootMetadata = ManagedOpenClawServiceBootMetadata | ManagedHermesServiceBootMetadata;
+/**
+ * Exact image-owned startup contract for a managed Gateway VM.
+ *
+ * This contract intentionally contains no executable, argv, shell command,
+ * callback, process handle, or resolved environment value. The image build
+ * maps each closed `bootEntry` discriminator to code-owned process startup.
+ */
+interface ManagedGatewayBootContract {
+  readonly contractVersion: 1;
+  readonly frameworkService: ManagedFrameworkServiceBootMetadata;
+  readonly kind: 'managed-gateway-exact-two-role';
+  readonly toolPortalService: ManagedToolPortalServiceBootMetadata;
+}
+/**
+ * Parses untrusted or serialized boot metadata into the exact V1 contract.
+ * Unknown fields are rejected at every level and a fresh deeply frozen value
+ * is returned so callers cannot retain mutation authority after validation.
+ */
+declare function parseManagedGatewayBootContract(value: unknown): ManagedGatewayBootContract;
+//#endregion
+//#region src/gateway-lifecycle.d.ts
+/**
+ * Describes how to run interactive auth for a gateway type.
+ * Static property — available without a running VM.
+ */
+interface GatewayAuthConfig {
+  /**
+   * Shell command to list available auth providers inside the VM.
+   * Should output one provider name per line to stdout.
+   */
+  readonly listProvidersCommand: string;
+  /**
+   * Build the shell command for interactive auth login.
+   * The CLI passes this as the SSH remote command with -t (TTY).
+   */
+  readonly buildLoginCommand: (provider: string, options?: {
+    readonly deviceCode?: boolean;
+    readonly agentId?: string;
+    readonly profileId?: string;
+  }) => string;
+  /**
+   * Build the shell command for listing provider auth profiles for one agent.
+   * The CLI uses this after login to verify requested profile IDs exist.
+   */
+  readonly buildProfileListCommand: (provider: string, options: {
+    readonly agentId: string;
+  }) => string;
+}
+interface GatewayAuthProfilesRef {
+  readonly source: '1password' | 'config' | 'environment';
+}
+interface OnePasswordGatewayAuthProfilesRef extends GatewayAuthProfilesRef {
+  readonly source: '1password';
+  readonly ref: string;
+}
+interface EnvironmentGatewayAuthProfilesRef extends GatewayAuthProfilesRef {
+  readonly source: 'environment';
+  readonly envVar: string;
+}
+interface ConfigGatewayAuthProfilesRef extends GatewayAuthProfilesRef {
+  readonly source: 'config';
+  readonly value: string;
+}
+type GatewaySshSecretEnvMode = 'always' | 'explicit' | 'never';
+interface GatewaySshConfig {
+  readonly secretEnv: GatewaySshSecretEnvMode;
+}
+interface GatewayIngressConfig {
+  readonly upstreamHeaderTimeoutMs?: number;
+  readonly upstreamResponseTimeoutMs?: number;
+}
+interface OpenClawGatewayControlAuthConfig {
+  readonly mode: 'token';
+  readonly secret: string;
+}
+interface OpenClawAuthLoginProviderConfig {
+  readonly profileIds: readonly string[];
+}
+interface OpenClawAuthLoginConfig {
+  readonly defaultAgent?: string;
+  readonly providers: Readonly<Record<string, OpenClawAuthLoginProviderConfig>>;
+}
+interface GatewayZoneBaseGatewayConfig {
+  readonly type: GatewayType;
+  readonly memory: string;
+  readonly cpus: number;
+  readonly port: number;
+  readonly ingress?: GatewayIngressConfig;
+  readonly config: string;
+  readonly stateDir: string;
+  readonly runtimeRootfsSize?: string;
+  readonly ssh: GatewaySshConfig;
+}
+interface OpenClawGatewayZoneGatewayConfig extends GatewayZoneBaseGatewayConfig {
+  readonly type: 'openclaw';
+  readonly controlAuth: OpenClawGatewayControlAuthConfig;
+  readonly zoneFilesDir: string;
+  readonly authProfilesRef?: ConfigGatewayAuthProfilesRef | OnePasswordGatewayAuthProfilesRef | EnvironmentGatewayAuthProfilesRef | undefined;
+  readonly authProfilesByAgent?: Readonly<Record<string, ConfigGatewayAuthProfilesRef | OnePasswordGatewayAuthProfilesRef | EnvironmentGatewayAuthProfilesRef>>;
+  readonly authLogin?: OpenClawAuthLoginConfig;
+  readonly rawEnvSecrets?: readonly string[];
+}
+interface HermesGatewayZoneGatewayConfig extends GatewayZoneBaseGatewayConfig {
+  readonly type: 'hermes';
+  readonly zoneFilesDir: string;
+  readonly profilesByAgent: Readonly<Record<string, string>>;
+}
+interface WorkerGatewayZoneGatewayConfig extends GatewayZoneBaseGatewayConfig {
+  readonly type: 'worker';
+}
+type GatewayZoneGatewayConfig = OpenClawGatewayZoneGatewayConfig | HermesGatewayZoneGatewayConfig | WorkerGatewayZoneGatewayConfig;
+interface OnePasswordSecretSourceConfig {
+  readonly source: '1password';
+  readonly ref: string;
+}
+interface EnvironmentSecretSourceConfig {
+  readonly source: 'environment';
+  readonly envVar: string;
+}
+interface ConfigSecretSourceConfig {
+  readonly source: 'config';
+  readonly value: string;
+}
+type SecretSourceConfig = OnePasswordSecretSourceConfig | EnvironmentSecretSourceConfig | ConfigSecretSourceConfig;
+type EnvInjectedGatewaySecretConfig = SecretSourceConfig & {
+  readonly audience: 'gateway';
+  readonly injection: 'env';
+};
+type HttpMediatedGatewaySecretConfig = SecretSourceConfig & {
+  readonly audience: VmAudience;
+  readonly injection: 'http-mediation';
+  readonly hosts: readonly string[];
+};
+type GatewaySecretConfig = EnvInjectedGatewaySecretConfig | HttpMediatedGatewaySecretConfig;
+declare const gatewayToolPortalTelemetryServiceName: "agent-vm-tool-portal";
+declare const gatewayFrameworkTelemetryServiceNames: Readonly<{
+  hermes: "agent-vm-hermes";
+  openclaw: "agent-vm-openclaw";
+}>;
+declare const gatewayTelemetrySourcePolicy: Readonly<{
+  admitBaggage: false;
+  captureContent: false;
+}>;
+declare const gatewayTelemetryAdmissionLimits: Readonly<{
+  maxExportBatchRecords: 64;
+  maxQueuedRecordsPerSignal: 256;
+  maxRecordBytes: 65536;
+}>;
+type GatewayTelemetrySourcePolicy = typeof gatewayTelemetrySourcePolicy;
+type GatewayTelemetryAdmissionLimits = typeof gatewayTelemetryAdmissionLimits;
+interface GatewayTelemetrySignalPolicy {
+  readonly traces: boolean;
+  readonly metrics: boolean;
+  readonly logs: boolean;
+  readonly sampleRate: number;
+  readonly flushIntervalMs: number;
+}
+interface GatewayTelemetryProducerSafetyContract {
+  readonly admissionLimits: GatewayTelemetryAdmissionLimits;
+  readonly sourcePolicy: GatewayTelemetrySourcePolicy;
+}
+interface GatewayFrameworkTelemetryProducerConfig extends GatewayTelemetrySignalPolicy, GatewayTelemetryProducerSafetyContract {
+  readonly serviceName: (typeof gatewayFrameworkTelemetryServiceNames)[keyof typeof gatewayFrameworkTelemetryServiceNames];
+}
+interface GatewayToolPortalTelemetryProducerConfig extends GatewayTelemetrySignalPolicy, GatewayTelemetryProducerSafetyContract {
+  readonly serviceName: typeof gatewayToolPortalTelemetryServiceName;
+}
+declare function createGatewayTelemetryProducerSafetyContract(): GatewayTelemetryProducerSafetyContract;
+interface GatewayZoneObservabilityConfig {
+  readonly mode: 'collector';
+  readonly collector: {
+    readonly host: string;
+    readonly grpcPort: number;
+    readonly httpPort: number;
+    readonly targetHost: string;
+    readonly targetGrpcPort: number;
+    readonly targetHttpPort: number;
+  };
+  readonly framework: GatewayFrameworkTelemetryProducerConfig;
+  readonly openclaw?: {
+    readonly diagnosticsFlags: readonly string[];
+  };
+  readonly toolPortal: GatewayToolPortalTelemetryProducerConfig;
+}
+/**
+ * Zone config as the lifecycle sees it.
+ * Decoupled from SystemConfig — the controller maps into this shape.
+ */
+interface GatewayZoneConfig {
+  readonly id: string;
+  readonly agents?: readonly GatewayZoneAgentConfig[];
+  readonly gateway: GatewayZoneGatewayConfig;
+  readonly toolPortal?: GatewayZoneMcpPortalConfig;
+  readonly runtimeMcpServers?: Readonly<Record<string, GatewayZoneMcpServerConfig>>;
+  readonly runtimeMediatedSecrets?: Readonly<Record<string, MediatedSecretSpec>>;
+  readonly runtimeEnvironment?: Readonly<Record<string, string>>;
+  readonly runtimePrivateEnvironment?: Readonly<Partial<Record<GatewayControlPrivateEnvironmentName, string>>>;
+  readonly runtimePluginConfigs?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  readonly gitReadAllowlistRepos?: readonly string[];
+  readonly observability?: GatewayZoneObservabilityConfig;
+  readonly secrets: Readonly<Record<string, GatewaySecretConfig>>;
+  readonly egressHosts: readonly EgressHostConfig[];
+  readonly websocketUpgrades?: readonly WebSocketUpgradeConfig[];
+  readonly defaultToolVmProfile?: string;
+}
+interface GatewayZoneAgentConfig {
+  readonly id: string;
+  readonly toolVmProfile?: string | undefined;
+}
+interface GatewayZoneMcpPortalConfig {
+  readonly configDir: string;
+}
+interface GatewayZoneMcpServerConfig {
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly transport: 'streamable-http';
+  readonly url: string;
+}
+interface BuildGatewayVmRequirementsOptions {
+  readonly controllerPort: number;
+  readonly gatewayCacheDir: string;
+  readonly projectNamespace: string;
+  readonly resolvedSecrets: Record<string, string>;
+  readonly runtimeDir: string;
+  readonly tcpPool: {
+    readonly basePort: number;
+    readonly size: number;
+  };
+  readonly zone: GatewayZoneConfig;
+}
+interface GatewayLifecycleBase {
+  /**
+   * How to run interactive auth for this gateway type.
+   * Absent means the gateway type does not support interactive auth.
+   */
+  readonly authConfig?: GatewayAuthConfig | undefined;
+  /**
+   * Build backend-neutral guest workload requirements.
+   * Pure data assembly — no side effects or controller authority.
+   */
+  buildVmRequirements(options: BuildGatewayVmRequirementsOptions): GatewayVmRequirements;
+  /**
+   * Optional hook to prepare host-side state before the VM boots.
+   * Example: writing auth-profiles.json from 1Password.
+   */
+  prepareHostState?(zone: GatewayZoneConfig, secretResolver: SecretResolver): Promise<void>;
+  /**
+   * Optional hook to resolve host-state secret dependencies without writing
+   * host state. Protected restarts use this before closing a live gateway so
+   * secret-resolution failures do not strand the zone without a VM.
+   */
+  preflightHostState?(zone: GatewayZoneConfig, secretResolver: SecretResolver): Promise<void>;
+}
+interface BuildManagedFrameworkServiceBootInputsOptions {
+  readonly resolvedSecrets: Record<string, string>;
+  readonly zone: GatewayZoneConfig;
+}
+/**
+ * Sensitive framework-service inputs that the controller materializes into
+ * the protected, immutable Managed Gateway boot-input directory.
+ *
+ * This contract intentionally contains no executable, argv, callback,
+ * process handle, or controller authority.
+ */
+interface ManagedFrameworkServiceBootInputsBase {
+  readonly configuration: unknown;
+  readonly environment: Readonly<Record<string, string>>;
+}
+interface ManagedFrameworkServiceConfigurationOnlyBootInputs extends ManagedFrameworkServiceBootInputsBase {
+  readonly kind: 'configuration-only';
+}
+interface ManagedHermesFrameworkServiceBootInputs extends ManagedFrameworkServiceBootInputsBase {
+  readonly kind: 'hermes-managed-scope';
+  readonly managedConfigurationSource: string;
+}
+type ManagedFrameworkServiceBootInputs = ManagedFrameworkServiceConfigurationOnlyBootInputs | ManagedHermesFrameworkServiceBootInputs;
+interface ManagedGatewayLifecycle extends GatewayLifecycleBase {
+  readonly executionModel: 'managed-gateway';
+  /** Build the selected framework half of the exact managed boot contract. */
+  buildFrameworkServiceBootMetadata(zone: GatewayZoneConfig): ManagedFrameworkServiceBootMetadata;
+  /** Build service-scoped config and environment for protected materialization. */
+  buildFrameworkServiceBootInputs(options: BuildManagedFrameworkServiceBootInputsOptions): Promise<ManagedFrameworkServiceBootInputs>;
+}
+interface DirectProcessGatewayLifecycle extends GatewayLifecycleBase {
+  readonly executionModel: 'direct-process';
+  /**
+   * Build the direct-process spec retained only by standalone Worker.
+   * Pure data assembly — no side effects.
+   */
+  buildProcessSpec(zone: GatewayZoneConfig, resolvedSecrets: Record<string, string>): GatewayProcessSpec;
+}
+type GatewayLifecycle = ManagedGatewayLifecycle | DirectProcessGatewayLifecycle;
+//#endregion
+//#region src/health/controller-request-policy.d.ts
+declare const gatewayInternalControllerRequestOperations: readonly ["workspace-git-push", "lease-create", "lease-get", "lease-peek", "lease-renew", "lease-release", "lease-use-start", "lease-heartbeat", "lease-use-end"];
+type GatewayInternalControllerRequestOperation = (typeof gatewayInternalControllerRequestOperations)[number];
+type ControllerRequestPolicyOperation = GatewayInternalControllerRequestOperation;
+declare const dedicatedControllerRequestHealthEventOperations: readonly ["lease-heartbeat", "lease-renew"];
+type DedicatedControllerRequestHealthEventOperation = (typeof dedicatedControllerRequestHealthEventOperations)[number];
+type GenericControllerRequestEventOperation = Exclude<ControllerRequestPolicyOperation, DedicatedControllerRequestHealthEventOperation>;
+declare const genericControllerRequestEventOperations: GenericControllerRequestEventOperation[];
+declare const externalControllerRoutes: readonly ["GET /controller-status", "GET /zones/:zoneId/status", "GET /zones/:zoneId/health", "GET /zones/:zoneId/logs", "POST /zones/:zoneId/credentials/refresh", "POST /zones/:zoneId/destroy", "POST /zones/:zoneId/upgrade", "GET /zones/:zoneId/tasks/:taskId", "POST /zones/:zoneId/worker-tasks", "POST /zones/:zoneId/tasks/:taskId/close", "POST /zones/:zoneId/enable-ssh", "POST /zones/:zoneId/execute-command", "POST /stop-controller"];
+type ExternalControllerRoute = (typeof externalControllerRoutes)[number];
+type ControllerRequestPolicyIdempotency = 'read' | 'safe-mutation' | 'unsafe-mutation';
+interface ControllerRequestPolicyBase {
+  readonly idempotency: ControllerRequestPolicyIdempotency;
+  readonly timeoutMs: number;
+}
+type ControllerRequestPolicy = (ControllerRequestPolicyBase & {
+  readonly maxAttempts: 1;
+  readonly retryBaseDelayMs: 0;
+  readonly retryEnabled: false;
+  readonly retryStatuses: readonly [];
+}) | (ControllerRequestPolicyBase & {
+  readonly maxAttempts: number;
+  readonly retryBaseDelayMs: number;
+  readonly retryEnabled: true;
+  readonly retryStatuses: readonly [number, ...number[]];
+});
+type ControllerRequestPolicyTransportErrorCode = 'controller-request-failed' | 'controller-request-timeout';
+declare class ControllerRequestPolicyTransportError extends Error {
+  readonly code: ControllerRequestPolicyTransportErrorCode;
+  readonly operation: ControllerRequestPolicyOperation;
+  constructor(options: {
+    readonly cause: unknown;
+    readonly code: ControllerRequestPolicyTransportErrorCode;
+    readonly operation: ControllerRequestPolicyOperation;
+  });
+}
+declare function drainControllerResponseBody(response: Response): Promise<void>;
+declare const controllerRequestPolicies: {
+  'workspace-git-push': {
+    idempotency: "unsafe-mutation";
+    maxAttempts: 1;
+    retryBaseDelayMs: 0;
+    retryEnabled: false;
+    retryStatuses: [];
+    timeoutMs: number;
+  };
+  'lease-create': {
+    idempotency: "unsafe-mutation";
+    maxAttempts: 1;
+    retryBaseDelayMs: 0;
+    retryEnabled: false;
+    retryStatuses: [];
+    timeoutMs: number;
+  };
+  'lease-get': {
+    idempotency: "read";
+    maxAttempts: number;
+    retryBaseDelayMs: number;
+    retryEnabled: true;
+    retryStatuses: [number, number];
+    timeoutMs: number;
+  };
+  'lease-peek': {
+    idempotency: "read";
+    maxAttempts: number;
+    retryBaseDelayMs: number;
+    retryEnabled: true;
+    retryStatuses: [number, number];
+    timeoutMs: number;
+  };
+  'lease-renew': {
+    idempotency: "safe-mutation";
+    maxAttempts: number;
+    retryBaseDelayMs: number;
+    retryEnabled: true;
+    retryStatuses: [number, number, number];
+    timeoutMs: number;
+  };
+  'lease-release': {
+    idempotency: "safe-mutation";
+    maxAttempts: number;
+    retryBaseDelayMs: number;
+    retryEnabled: true;
+    retryStatuses: [number, number];
+    timeoutMs: number;
+  };
+  'lease-use-start': {
+    idempotency: "safe-mutation";
+    maxAttempts: number;
+    retryBaseDelayMs: number;
+    retryEnabled: true;
+    retryStatuses: [number, number, number];
+    timeoutMs: number;
+  };
+  'lease-heartbeat': {
+    idempotency: "safe-mutation";
+    maxAttempts: number;
+    retryBaseDelayMs: number;
+    retryEnabled: true;
+    retryStatuses: [number, number, number];
+    timeoutMs: number;
+  };
+  'lease-use-end': {
+    idempotency: "safe-mutation";
+    maxAttempts: number;
+    retryBaseDelayMs: number;
+    retryEnabled: true;
+    retryStatuses: [number, number];
+    timeoutMs: number;
+  };
+};
+//#endregion
+//#region src/health/agent-vm-health.d.ts
+declare const agentVmHealthEventKinds: readonly ["gateway-service-health", "gateway-control-session", "controller-request", "lease-renew", "lease-heartbeat", "caller-context-rejection", "tool-vm-ssh", "gateway-plugin-health", "agent-channel-provider-health", "gateway-recovery", "gateway-recovery-suspended"];
+type AgentVmHealthEventKind = (typeof agentVmHealthEventKinds)[number];
+declare const agentVmHealthResultKinds: readonly ["ok", "failed", "timeout", "stale"];
+type AgentVmHealthResultKind = (typeof agentVmHealthResultKinds)[number];
+interface AgentVmHealthEventBase {
+  readonly causationId?: string | undefined;
+  readonly correlationId?: string | undefined;
+  readonly observedAtMs: number;
+  readonly requestId?: string | undefined;
+  readonly result: AgentVmHealthResultKind;
+  readonly runId?: string | undefined;
+  readonly sessionKeyDigest?: string | undefined;
+  readonly toolCallId?: string | undefined;
+  readonly traceId?: string | undefined;
+  readonly zoneId: string;
+}
+type ToolVmSshHealthOperation = 'command' | 'file-bridge' | 'finalize' | 'probe';
+declare const toolVmLeaseLifecycleEventRoles: readonly ["plugin_observation", "controller_final"];
+type ToolVmLeaseLifecycleEventRole = (typeof toolVmLeaseLifecycleEventRoles)[number];
+declare const toolVmLeaseLifecycleTransitions: readonly ["current_to_stale", "current_to_retired", "deprecated_to_reacquired", "deprecated_to_retired", "stale_to_reacquired", "stale_to_retired", "retired_rejected"];
+type ToolVmLeaseLifecycleTransition = (typeof toolVmLeaseLifecycleTransitions)[number];
+declare const toolVmLeaseReacquiredLifecycleTransitions: readonly ["deprecated_to_reacquired", "stale_to_reacquired"];
+type ToolVmLeaseReacquiredLifecycleTransition = (typeof toolVmLeaseReacquiredLifecycleTransitions)[number];
+type ToolVmLeaseNonReacquiredLifecycleTransition = Exclude<ToolVmLeaseLifecycleTransition, ToolVmLeaseReacquiredLifecycleTransition>;
+declare const toolVmLeaseCallerContextStates: readonly ["ok", "absent", "stale", "session_mismatch", "not_applicable"];
+type ToolVmLeaseCallerContextState = (typeof toolVmLeaseCallerContextStates)[number];
+declare const toolVmLeaseRejectionReasons: readonly ["caller_context_absent", "caller_context_session_mismatch", "caller_context_stale", "lease_absent", "lease_authority_absent", "lease_force_released", "lease_generation_stale", "lease_reacquire_required", "lease_releasing", "lease_retired", "lease_use_tombstoned", "ownership_denied", "runtime_not_ready"];
+type ToolVmLeaseRejectionReason = (typeof toolVmLeaseRejectionReasons)[number];
+interface ToolVmLeaseLifecycleEvidenceBase {
+  readonly activeUseId?: string | undefined;
+  readonly callerContextState?: ToolVmLeaseCallerContextState | undefined;
+  readonly leaseRejectionReason?: ToolVmLeaseRejectionReason | undefined;
+  readonly lifecycleEventRole: ToolVmLeaseLifecycleEventRole;
+  readonly oldLeaseId: string;
+  readonly transitionId: string;
+}
+type ToolVmLeaseLifecycleEvidence = (ToolVmLeaseLifecycleEvidenceBase & {
+  readonly lifecycleTransition: ToolVmLeaseReacquiredLifecycleTransition;
+  readonly replacementLeaseId: string;
+}) | (ToolVmLeaseLifecycleEvidenceBase & {
+  readonly lifecycleTransition: ToolVmLeaseNonReacquiredLifecycleTransition;
+  readonly replacementLeaseId?: undefined;
+});
+interface ToolVmLeaseLifecycleAbsentEvidence {
+  readonly activeUseId?: undefined;
+  readonly callerContextState?: undefined;
+  readonly leaseRejectionReason?: undefined;
+  readonly lifecycleEventRole?: undefined;
+  readonly lifecycleTransition?: undefined;
+  readonly oldLeaseId?: undefined;
+  readonly replacementLeaseId?: undefined;
+  readonly transitionId?: undefined;
+}
+declare const agentChannelProviderHealthKinds: readonly ["healthy", "transitioning", "unhealthy-recoverable", "unhealthy-unrecoverable"];
+type AgentChannelProviderHealthKind = (typeof agentChannelProviderHealthKinds)[number];
+declare const agentChannelProviderHealthDetailKeys: readonly ["closeCode", "providerType", "reconnectAttempt", "reconnecting", "sleepResumeSuspected", "statusCode"];
+type AgentChannelProviderHealthDetailKey = (typeof agentChannelProviderHealthDetailKeys)[number];
+type AgentChannelProviderHealthDetails = Readonly<Partial<Record<AgentChannelProviderHealthDetailKey, boolean | number | string>>>;
+declare const gatewayRecoveryHealthReasons: readonly ["agent-channel-provider-unhealthy", "gateway-control-session-unhealthy", "gateway-service-unhealthy"];
+type GatewayRecoveryHealthReason = (typeof gatewayRecoveryHealthReasons)[number];
+type GatewayRecoveryVmAction = 'gateway-vm-cold-start' | 'gateway-vm-restart';
+type GatewayRecoveryEventAction = GatewayRecoveryVmAction | 'observe-only' | 'operator-required';
+type GatewayRecoveryTimeoutErrorCode = 'recovery-callback-unconfigured' | 'recovery-timeout';
+declare const gatewayControlSessionHealthOperations: readonly ["control-session-hello", "control-session-heartbeat", "control-session-disconnect", "control-session-reconnect"];
+type GatewayControlSessionHealthOperation = (typeof gatewayControlSessionHealthOperations)[number];
+type AgentVmHealthEvent = (AgentVmHealthEventBase & {
+  readonly kind: 'caller-context-rejection';
+  readonly operation: 'lease_create' | 'lease_get' | 'lease_peek' | 'lease_reacquire' | 'lease_release' | 'lease_renew' | 'lease_use_end' | 'lease_use_heartbeat' | 'lease_use_start';
+  readonly reason: 'caller_context_absent' | 'caller_context_session_mismatch' | 'caller_context_stale';
+  readonly result: 'failed';
+}) | (AgentVmHealthEventBase & {
+  readonly kind: 'gateway-service-health';
+  readonly path: string;
+  readonly port: number;
+  readonly statusCode?: number | undefined;
+}) | (AgentVmHealthEventBase & {
+  readonly bootId?: string | undefined;
+  readonly connectionId?: string | undefined;
+  readonly domain: 'gateway_control';
+  readonly elapsedMs: number;
+  readonly kind: 'gateway-control-session';
+  readonly operation: GatewayControlSessionHealthOperation;
+  readonly peerId: string;
+  readonly sessionId?: string | undefined;
+}) | (AgentVmHealthEventBase & {
+  readonly attempt: number;
+  readonly elapsedMs: number;
+  readonly errorCode?: string | undefined;
+  readonly kind: 'controller-request';
+  readonly maxAttempts: number;
+  readonly operation: GenericControllerRequestEventOperation;
+  readonly statusCode?: number | undefined;
+}) | (AgentVmHealthEventBase & {
+  readonly agentId: string;
+  readonly elapsedMs: number;
+  readonly errorCode?: string | undefined;
+  readonly kind: 'lease-renew';
+  readonly leaseId: string;
+}) | (AgentVmHealthEventBase & {
+  readonly agentId: string;
+  readonly elapsedMs: number;
+  readonly errorCode?: string | undefined;
+  readonly kind: 'lease-heartbeat';
+  readonly leaseId: string;
+  readonly useId: string;
+}) | (AgentVmHealthEventBase & {
+  readonly agentId: string;
+  readonly elapsedMs: number;
+  readonly errorCode?: string | undefined;
+  readonly kind: 'tool-vm-ssh';
+  readonly leaseId: string;
+  readonly operation: ToolVmSshHealthOperation;
+} & (ToolVmLeaseLifecycleAbsentEvidence | ToolVmLeaseLifecycleEvidence)) | (AgentVmHealthEventBase & {
+  readonly gatewayService: GatewayType;
+  readonly kind: 'gateway-plugin-health';
+  readonly state: 'starting' | 'ready' | 'stopping' | 'failed';
+}) | (AgentVmHealthEventBase & {
+  readonly channelProviderId: string;
+  readonly details?: AgentChannelProviderHealthDetails | undefined;
+  readonly health: AgentChannelProviderHealthKind;
+  readonly kind: 'agent-channel-provider-health';
+  readonly transitionStartedAtMs?: number | undefined;
+  readonly unhealthySinceMs?: number | undefined;
+}) | (AgentVmHealthEventBase & {
+  readonly action: 'gateway-vm-restart';
+  readonly consecutiveFailures: number;
+  readonly cooldownMs: number;
+  readonly elapsedMs: number;
+  readonly kind: 'gateway-recovery';
+  readonly leaseReleaseFailureCount: number;
+  readonly newBootedAt: string;
+  readonly newHostPid: number;
+  readonly newVmId: string;
+  readonly oldBootedAt: string;
+  readonly oldHostPid: number;
+  readonly oldVmId: string;
+  readonly operationId?: string | undefined;
+  readonly reason: GatewayRecoveryHealthReason;
+  readonly result: 'ok';
+}) | (AgentVmHealthEventBase & {
+  readonly action: 'gateway-vm-cold-start';
+  readonly consecutiveFailures: number;
+  readonly cooldownMs: number;
+  readonly elapsedMs: number;
+  readonly kind: 'gateway-recovery';
+  readonly leaseReleaseFailureCount: number;
+  readonly newBootedAt: string;
+  readonly newHostPid: number;
+  readonly newVmId: string;
+  readonly oldBootedAt?: undefined;
+  readonly oldHostPid?: undefined;
+  readonly oldVmId?: undefined;
+  readonly operationId?: string | undefined;
+  readonly reason: GatewayRecoveryHealthReason;
+  readonly result: 'ok';
+}) | (AgentVmHealthEventBase & {
+  readonly action: 'gateway-vm-restart';
+  readonly consecutiveFailures: number;
+  readonly cooldownMs: number;
+  readonly elapsedMs: number;
+  readonly errorCode: string;
+  readonly kind: 'gateway-recovery';
+  readonly leaseReleaseFailureCount?: number | undefined;
+  readonly oldBootedAt?: string | undefined;
+  readonly oldHostPid?: number | undefined;
+  readonly oldVmId: string;
+  readonly operationId?: string | undefined;
+  readonly reason: GatewayRecoveryHealthReason;
+  readonly result: 'failed';
+}) | (AgentVmHealthEventBase & {
+  readonly action: 'gateway-vm-restart';
+  readonly consecutiveFailures: number;
+  readonly cooldownMs: number;
+  readonly elapsedMs: number;
+  readonly errorCode: GatewayRecoveryTimeoutErrorCode;
+  readonly kind: 'gateway-recovery';
+  readonly leaseReleaseFailureCount?: number | undefined;
+  readonly oldBootedAt?: string | undefined;
+  readonly oldHostPid?: number | undefined;
+  readonly oldVmId?: string | undefined;
+  readonly operationId?: string | undefined;
+  readonly reason: GatewayRecoveryHealthReason;
+  readonly result: 'failed';
+}) | (AgentVmHealthEventBase & {
+  readonly action: 'gateway-vm-cold-start' | 'observe-only' | 'operator-required';
+  readonly consecutiveFailures: number;
+  readonly cooldownMs: number;
+  readonly elapsedMs: number;
+  readonly errorCode: string;
+  readonly kind: 'gateway-recovery';
+  readonly leaseReleaseFailureCount?: number | undefined;
+  readonly oldBootedAt?: undefined;
+  readonly oldHostPid?: undefined;
+  readonly oldVmId?: undefined;
+  readonly operationId?: string | undefined;
+  readonly reason: GatewayRecoveryHealthReason;
+  readonly result: 'failed';
+}) | (AgentVmHealthEventBase & {
+  readonly action: GatewayRecoveryEventAction;
+  readonly consecutiveFailedRecoveries: number;
+  readonly consecutiveFailures: number;
+  readonly cooldownMs: number;
+  readonly errorCode: 'max-failed-recoveries';
+  readonly failedRecoveryResetMs: number;
+  readonly kind: 'gateway-recovery-suspended';
+  readonly operationId?: string | undefined;
+  readonly reason: GatewayRecoveryHealthReason;
+  readonly result: 'failed';
+});
+declare const zoneHealthStateKinds: readonly ["unknown", "ok", "stale", "failed"];
+type ZoneHealthStateKind = (typeof zoneHealthStateKinds)[number];
+declare const zoneHealthIssueKinds: readonly ["gateway-service-unhealthy", "gateway-control-session-unhealthy", "controller-request-failing", "lease-heartbeat-failing", "lease-renew-failing", "tool-vm-ssh-failing", "gateway-plugin-unhealthy", "agent-channel-provider-unhealthy", "gateway-recovery-failed", "gateway-recovery-suspended", "health-event-stale"];
+type ZoneHealthIssueKind = (typeof zoneHealthIssueKinds)[number];
+interface ZoneHealthIssue {
+  readonly kind: ZoneHealthIssueKind;
+  readonly latestEvent: AgentVmHealthEvent;
+  readonly message: string;
+  readonly sinceMs: number;
+}
+type ZoneHealthSnapshot = {
+  readonly kind: 'unknown';
+  readonly reason: 'no-events';
+  readonly zoneId: string;
+} | {
+  readonly kind: 'ok';
+  readonly latestEvents: readonly AgentVmHealthEvent[];
+  readonly zoneId: string;
+} | {
+  readonly issues: readonly ZoneHealthIssue[];
+  readonly kind: 'stale' | 'failed';
+  readonly latestEvents: readonly AgentVmHealthEvent[];
+  readonly zoneId: string;
+};
+interface DeriveZoneHealthSnapshotOptions {
+  readonly nowMs: number;
+  readonly staleAfterMs: number;
+  readonly zoneId: string;
+}
+declare function isAgentVmHealthEvent(value: unknown): value is AgentVmHealthEvent;
+declare function healthEventBucketKey(event: AgentVmHealthEvent): string;
+declare function deriveZoneHealthSnapshot(events: readonly AgentVmHealthEvent[], options: DeriveZoneHealthSnapshotOptions): ZoneHealthSnapshot;
+//#endregion
+//#region src/git-read-allowlist.d.ts
+interface NormalizedGitSshReadAllowlistEntry {
+  readonly host: string;
+  readonly repoPath: string;
+}
+interface NormalizedGitSshReadAllowlist {
+  readonly allowedHosts: readonly string[];
+  readonly allowedRepos: readonly string[];
+}
+declare function normalizeGitRepoForSshReadAllowlist(repoUrl: string): NormalizedGitSshReadAllowlistEntry | undefined;
+declare function normalizeGitReposForSshReadAllowlist(repoUrls: readonly string[] | undefined): NormalizedGitSshReadAllowlist;
+declare function normalizeGitHubRepoForSshReadAllowlist(repoUrl: string): string | undefined;
+declare function normalizeGitHubReposForSshReadAllowlist(repoUrls: readonly string[] | undefined): readonly string[];
+//#endregion
+//#region src/force-ipv4-egress.d.ts
+/**
+ * Canonical NODE_OPTIONS value for forcing IPv4-preference egress
+ * in agent-vm VMs.
+ *
+ * Background: the managed VM synthetic DNS path (when tcpHosts is enabled)
+ * returns a per-host IPv4 (reverse-lookable) and a single shared
+ * IPv4-mapped IPv6 (::ffff:198.18.0.1, NOT reverse-lookable). Node
+ * 20+'s fetch (via undici, autoSelectFamily: true) races both
+ * families; when the IPv6 race wins (~5-20% under sequential load),
+ * the VM egress router cannot route it and the request fails with a non-JSON
+ * 400 (HTTP) or 403 (TLS). The two flags below stop the race:
+ *
+ *   --dns-result-order=ipv4first       changes dns.lookup() so
+ *                                      IPv4 addresses are listed
+ *                                      before IPv6.
+ *
+ *   --no-network-family-autoselection  disables Node's Happy
+ *                                      Eyeballs entirely. This is
+ *                                      the load-bearing flag —
+ *                                      --dns-result-order alone
+ *                                      doesn't prevent Node from
+ *                                      racing both families if
+ *                                      IPv4 is slow.
+ *
+ * Composition: NODE_OPTIONS is whitespace-separated. To add more
+ * flags downstream, append rather than replace. Example:
+ *
+ *   NODE_OPTIONS: `${FORCE_IPV4_EGRESS_NODE_OPTIONS} --inspect`
+ *
+ * Reference: see `shravan-claw@0ddf5f2:docs/wip/debugging/
+ * 2026-05-21-lease-keepalive-400-and-discord-403-ipv6-race.md`
+ * for the full root-cause analysis. Node-side flag references:
+ * https://github.com/nodejs/node/issues/54359 (autoSelectFamily
+ * revert recommendation by the Node core team).
+ */
+declare const FORCE_IPV4_EGRESS_NODE_OPTIONS = "--dns-result-order=ipv4first --no-network-family-autoselection";
+/**
+ * Compose the forced IPv4-preference flags with a user-provided
+ * NODE_OPTIONS value (if any).
+ *
+ * Use this at every site where NODE_OPTIONS is set into a VM env
+ * block AFTER a spread of user-controlled secrets, to guarantee
+ * the forced flags are always present in the final value even if
+ * a zone secret happens to provide its own NODE_OPTIONS.
+ *
+ * Forced flags come FIRST so they are unambiguously applied.
+ * User-provided flags are appended verbatim except for duplicate
+ * forced IPv4-preference flags. Node treats NODE_OPTIONS as a
+ * whitespace-separated list and all flags apply.
+ *
+ * Returns just the forced flags if the user value is undefined,
+ * empty, or whitespace-only.
+ *
+ * Examples:
+ *
+ *   composeNodeOptions(undefined)
+ *     ──► '--dns-result-order=ipv4first --no-network-family-autoselection'
+ *
+ *   composeNodeOptions('')
+ *     ──► '--dns-result-order=ipv4first --no-network-family-autoselection'
+ *
+ *   composeNodeOptions('--inspect=0.0.0.0:9229')
+ *     ──► '--dns-result-order=ipv4first --no-network-family-autoselection
+ *          --inspect=0.0.0.0:9229'
+ */
+declare function composeNodeOptions(userValue: string | undefined): string;
+//#endregion
+//#region src/split-resolved-gateway-secrets.d.ts
+interface SplitResolvedSecretsResult {
+  readonly environmentSecrets: Record<string, string>;
+  readonly mediatedSecrets: Record<string, MediatedSecretSpec>;
+}
+interface MergeRuntimeGatewaySecretsOptions {
+  readonly logPrefix?: string;
+  readonly runtimeEnvironment?: Readonly<Record<string, string>> | undefined;
+  readonly runtimeMediatedSecrets?: Readonly<Record<string, MediatedSecretSpec>> | undefined;
+}
+type SecretInjectionConfig = GatewaySecretConfig;
+interface SplitResolvedSecretsOptions {
+  readonly audience: RuntimeVmAudience;
+  readonly logPrefix?: string;
+}
+declare function splitResolvedSecretsByInjection(secretConfigs: Readonly<Record<string, SecretInjectionConfig>>, resolvedSecrets: Record<string, string>, options: SplitResolvedSecretsOptions): SplitResolvedSecretsResult;
+type SplitResolvedGatewaySecretsResult = SplitResolvedSecretsResult;
+declare function splitResolvedGatewaySecrets(zone: GatewayZoneConfig, resolvedSecrets: Record<string, string>): SplitResolvedGatewaySecretsResult;
+declare function mergeRuntimeGatewaySecrets(baseSecrets: SplitResolvedSecretsResult, options?: MergeRuntimeGatewaySecretsOptions): SplitResolvedSecretsResult;
+//#endregion
+//#region src/tool-vm-active-use.d.ts
+type ToolVmActiveUseOutcome = 'abandoned' | 'cancelled' | 'completed' | 'failed' | 'timed-out';
+interface ToolVmActiveUseCorrelation {
+  readonly messageId?: string | undefined;
+  readonly requestId?: string | undefined;
+  readonly runId?: string | undefined;
+  readonly sessionKeyDigest?: string | undefined;
+  readonly toolCallId?: string | undefined;
+  readonly traceId?: string | undefined;
+}
+type ToolVmSshOperationPhase = 'completed' | 'failed' | 'probe-succeeded' | 'running' | 'starting';
+type ToolVmSshFailureKind = 'active-use-refreshable-failure' | 'ssh-command-failed' | 'ssh-command-timed-out' | 'ssh-probe-failed';
+interface ToolVmSshFailureReport {
+  readonly kind: ToolVmSshFailureKind;
+  readonly message: string;
+}
+interface ToolVmSshOperationReport {
+  readonly failure?: ToolVmSshFailureReport | undefined;
+  readonly probeSucceeded?: boolean | undefined;
+}
+interface ToolVmActiveUseOperationReport {
+  readonly observedAtMs: number;
+  readonly phase: ToolVmSshOperationPhase;
+  readonly ssh?: ToolVmSshOperationReport | undefined;
+}
+interface StartToolVmActiveUseRequest {
+  readonly correlation?: ToolVmActiveUseCorrelation | undefined;
+  readonly report?: ToolVmActiveUseOperationReport | undefined;
+  readonly useId: string;
+}
+interface StartToolVmActiveUseResponse {
+  readonly expiresAt: number;
+  readonly heartbeatAfterMs: number;
+  readonly useId: string;
+}
+interface HeartbeatToolVmActiveUseResponse {
+  readonly expiresAt: number;
+  readonly heartbeatAfterMs: number;
+}
+interface HeartbeatToolVmActiveUseRequest {
+  readonly report?: ToolVmActiveUseOperationReport | undefined;
+}
+interface EndToolVmActiveUseRequest {
+  readonly outcome: ToolVmActiveUseOutcome;
+  readonly report?: ToolVmActiveUseOperationReport | undefined;
+}
+interface ToolVmActiveUseHandle {
+  readonly signal: AbortSignal;
+  readonly useId: string;
+  dispose(outcome?: ToolVmActiveUseOutcome): Promise<void>;
+  end(outcome?: ToolVmActiveUseOutcome): Promise<void>;
+  report(report: ToolVmActiveUseOperationReport): void;
+}
+interface CreateToolVmActiveUseHandleOptions {
+  readonly correlation?: ToolVmActiveUseCorrelation | undefined;
+  readonly endActiveUse: (useId: string, request: EndToolVmActiveUseRequest) => Promise<void>;
+  readonly heartbeatActiveUse: (useId: string, request: HeartbeatToolVmActiveUseRequest) => Promise<HeartbeatToolVmActiveUseResponse>;
+  readonly heartbeatJitterRatio?: number | undefined;
+  readonly isEndErrorTolerable?: (error: unknown) => boolean;
+  readonly isHeartbeatErrorRefreshable?: (error: unknown) => boolean;
+  readonly logEndFailure?: (error: unknown) => void;
+  readonly logHeartbeatFailure?: (error: unknown) => void;
+  readonly maxHeartbeatDurationMs?: number | undefined;
+  readonly nowImpl?: (() => number) | undefined;
+  readonly onRefreshableHeartbeatFailure?: (error: unknown) => Promise<void>;
+  readonly randomImpl?: (() => number) | undefined;
+  readonly startActiveUse: (request: StartToolVmActiveUseRequest) => Promise<StartToolVmActiveUseResponse>;
+  readonly setTimeoutImpl?: typeof setTimeout | undefined;
+  readonly clearTimeoutImpl?: typeof clearTimeout | undefined;
+}
+declare function createToolVmActiveUseId(): string;
+declare function isToolVmActiveUseId(value: string): boolean;
+declare function normalizeToolVmActiveUseCorrelation(correlation: unknown): ToolVmActiveUseCorrelation | undefined;
+declare function createToolVmActiveUseHandle(options: CreateToolVmActiveUseHandleOptions): Promise<ToolVmActiveUseHandle>;
+//#endregion
+//#region src/runtime-paths/runtime-path-mapping.d.ts
+declare const TOOL_VM_SCRATCH_GUEST_ROOT = "/scratch";
+declare const OPENCLAW_STATE_VM_ROOT = "/home/openclaw/.openclaw/state";
+declare const OPENCLAW_STATE_SANDBOXES_VM_ROOT = "/home/openclaw/.openclaw/state/sandboxes";
+type RuntimePathNamespace = 'controller-host' | 'openclaw-gateway' | 'tool-vm-guest';
+type RuntimePathPurpose = 'executionCwd' | 'leaseMount';
+interface RuntimePathCapabilities {
+  readonly executionCwd: boolean;
+  readonly leaseMount: boolean;
+}
+type RuntimePathBacking = {
+  readonly kind: 'host-realfs';
+  readonly durability: 'durable' | 'runtime' | 'cache';
+  readonly backup: 'included' | 'excluded';
+} | {
+  readonly kind: 'guest-rootfs-cow';
+  readonly durability: 'vm-lifetime';
+};
+type RuntimePathLocations = Partial<Record<RuntimePathNamespace, string>>;
+type RuntimePathHostRealfsLocations = {
+  readonly 'controller-host': string;
+  readonly 'openclaw-gateway'?: string;
+  readonly 'tool-vm-guest'?: string;
+} | {
+  readonly 'controller-host'?: string;
+  readonly 'openclaw-gateway': string;
+  readonly 'tool-vm-guest'?: string;
+};
+interface RuntimePathGuestRootfsCowLocations {
+  readonly 'controller-host'?: never;
+  readonly 'openclaw-gateway'?: never;
+  readonly 'tool-vm-guest': string;
+}
+type RuntimePathGuidanceVisibility = Partial<Record<RuntimePathNamespace, boolean>>;
+interface RuntimePathRootMappingBase {
+  readonly capabilities: RuntimePathCapabilities;
+  readonly guidanceLabel: string;
+  readonly id: string;
+  /**
+   * False for broad roots like /zone where mounting the root would expose
+   * unrelated children; callers must request an explicit child path.
+   */
+  readonly rootPathAllowed: boolean;
+  readonly showInGuidance?: RuntimePathGuidanceVisibility;
+}
+type RuntimePathRootMapping = (RuntimePathRootMappingBase & {
+  readonly backing: Extract<RuntimePathBacking, {
+    readonly kind: 'host-realfs';
+  }>;
+  readonly locations: RuntimePathHostRealfsLocations;
+}) | (RuntimePathRootMappingBase & {
+  readonly backing: Extract<RuntimePathBacking, {
+    readonly kind: 'guest-rootfs-cow';
+  }>;
+  readonly capabilities: RuntimePathCapabilities & {
+    readonly leaseMount: false;
+  };
+  readonly locations: RuntimePathGuestRootfsCowLocations;
+});
+interface RuntimePathMapping {
+  readonly id: string;
+  readonly roots: readonly RuntimePathRootMapping[];
+}
+interface TranslateRuntimePathInput {
+  readonly inputPath: string;
+  readonly mapping: RuntimePathMapping;
+  readonly purpose: RuntimePathPurpose;
+  readonly sourceNamespace?: RuntimePathNamespace;
+  readonly targetNamespace: RuntimePathNamespace;
+}
+interface RuntimePathTranslation {
+  readonly backing: RuntimePathBacking;
+  readonly capabilities: RuntimePathCapabilities;
+  readonly inputNamespace: RuntimePathNamespace;
+  readonly inputPath: string;
+  readonly mappingId: string;
+  readonly outputNamespace: RuntimePathNamespace;
+  readonly outputPath: string;
+  readonly relativePath: string;
+  readonly rootId: string;
+}
+type RuntimePathTranslationErrorCode = 'path-not-absolute' | 'path-parent-traversal' | 'invalid-runtime-root' | 'unknown-runtime-path' | 'purpose-not-allowed' | 'root-path-not-allowed' | 'target-namespace-not-available';
+interface RuntimePathTranslationError {
+  readonly allowedPathForms: readonly string[];
+  readonly code: RuntimePathTranslationErrorCode;
+  readonly inputPath: string;
+  readonly mappingId: string;
+  readonly message: string;
+  readonly purpose: RuntimePathPurpose;
+  readonly retryGuidance: string;
+}
+type TranslateRuntimePathResult = {
+  readonly ok: true;
+  readonly value: RuntimePathTranslation;
+} | {
+  readonly ok: false;
+  readonly error: RuntimePathTranslationError;
+};
+declare function translateRuntimePath(input: TranslateRuntimePathInput): TranslateRuntimePathResult;
+//#endregion
+//#region src/tool-vm-lease-id.d.ts
+declare const toolVmLeaseIdBrand: unique symbol;
+type ToolVmLeaseId = string & {
+  readonly [toolVmLeaseIdBrand]: true;
+};
+declare function createToolVmLeaseId(): ToolVmLeaseId;
+declare function isToolVmLeaseId(value: unknown): value is ToolVmLeaseId;
+declare function parseToolVmLeaseId(value: unknown): ToolVmLeaseId;
+//#endregion
+//#region src/vm-capability-lease.d.ts
+/**
+ * Small host-issued capability envelope shared by VM-backed transports. The
+ * transport tag keeps SSH Tool VM leases distinct from future host-side
+ * VM RPC or bridge capabilities without inventing a transport object.
+ */
+interface VmCapabilityLease<TTransport extends string> {
+  readonly leaseId: string;
+  readonly transport: TTransport;
+}
+interface VmSshEndpoint {
+  readonly host: string;
+  readonly identityPem: string;
+  readonly knownHostsLine: string;
+  readonly port: number;
+  readonly user: string;
+}
+interface VmSshPublicEndpoint {
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+}
+interface VmSshLease<TTransport extends string> extends VmCapabilityLease<TTransport> {
+  readonly ssh: VmSshEndpoint;
+}
+declare function isVmCapabilityLease<TTransport extends string>(value: unknown, transport: TTransport): value is VmCapabilityLease<TTransport>;
+declare function isVmSshEndpoint(value: unknown): value is VmSshEndpoint;
+declare function isVmSshPublicEndpoint(value: unknown): value is VmSshPublicEndpoint;
+//#endregion
+//#region src/tool-vm-lease.d.ts
+declare const defaultToolVmLeaseAuthorityTombstoneTtlMs: number;
+declare const TOOL_VM_WORK_GUEST_ROOT = "/work";
+interface ToolVmSshLease extends VmSshLease<'ssh-sandbox'> {
+  readonly agentId: string;
+  readonly idleTtlMs: number;
+  readonly leaseId: ToolVmLeaseId;
+  readonly tcpSlot: number;
+  readonly workdir: string;
+}
+interface ToolVmLeasePeek extends VmCapabilityLease<'ssh-sandbox'> {
+  readonly agentId: string;
+  readonly createdAt: number;
+  readonly idleTtlMs: number;
+  readonly lastUsedAt: number;
+  readonly leaseId: ToolVmLeaseId;
+  readonly profileId: string;
+  readonly ssh: VmSshPublicEndpoint;
+  readonly tcpSlot: number;
+  readonly workdir: string;
+  readonly zoneId: string;
+}
+declare function isToolVmSshLease(value: unknown): value is ToolVmSshLease;
+declare function isToolVmLeasePeek(value: unknown): value is ToolVmLeasePeek;
+//#endregion
+export { type AgentChannelProviderHealthDetails, type AgentChannelProviderHealthKind, type AgentVmHealthEvent, type AgentVmHealthEventBase, type AgentVmHealthEventKind, type AgentVmHealthResultKind, type BuildGatewayVmRequirementsOptions, type BuildManagedFrameworkServiceBootInputsOptions, type ControllerRequestPolicy, type ControllerRequestPolicyOperation, ControllerRequestPolicyTransportError, type ControllerRequestPolicyTransportErrorCode, type CreateToolVmActiveUseHandleOptions, type DeriveZoneHealthSnapshotOptions, type DirectProcessGatewayLifecycle, type EgressHostConfig, type EndToolVmActiveUseRequest, type EnvInjectedGatewaySecretConfig, type ExternalControllerRoute, FORCE_IPV4_EGRESS_NODE_OPTIONS, GATEWAY_CONTROL_CALLER_CONTEXT_AGENT_AUTHORITY_KEYS_ENV, GATEWAY_CONTROL_CALLER_CONTEXT_PROOF_KEY_ENV, GATEWAY_CONTROL_PRIVATE_ENVIRONMENT_NAMES, type GatewayAuthConfig, type GatewayControlPrivateEnvironmentName, type GatewayControlSessionHealthOperation, type GatewayFrameworkTelemetryProducerConfig, type GatewayHealthCheck, type GatewayIngressConfig, type GatewayLifecycle, type GatewayLifecycleBase, type GatewayProcessSpec, type GatewayRecoveryEventAction, type GatewayRecoveryHealthReason, type GatewayRecoveryTimeoutErrorCode, type GatewayRecoveryVmAction, type GatewaySecretConfig, type GatewayTelemetryAdmissionLimits, type GatewayTelemetryProducerSafetyContract, type GatewayTelemetrySignalPolicy, type GatewayTelemetrySourcePolicy, type GatewayToolPortalTelemetryProducerConfig, type GatewayType, type GatewayVmRequirements, type GatewayZoneAgentConfig, type GatewayZoneConfig, type GatewayZoneMcpPortalConfig, type GatewayZoneObservabilityConfig, type GenericControllerRequestEventOperation, type HeartbeatToolVmActiveUseRequest, type HeartbeatToolVmActiveUseResponse, type HttpMediatedGatewaySecretConfig, type ManagedFrameworkBootEntry, type ManagedFrameworkIngressMetadata, type ManagedFrameworkKind, type ManagedFrameworkReadinessMetadata, type ManagedFrameworkServiceBootInputs, type ManagedFrameworkServiceBootMetadata, type ManagedGatewayBootContract, type ManagedGatewayLifecycle, type ManagedGatewayLogIdentity, type ManagedHermesServiceBootMetadata, type ManagedOpenClawServiceBootMetadata, type ManagedToolPortalReadinessMetadata, type ManagedToolPortalServiceBootMetadata, type NormalizedGitSshReadAllowlist, type NormalizedGitSshReadAllowlistEntry, OPENCLAW_STATE_SANDBOXES_VM_ROOT, OPENCLAW_STATE_VM_ROOT, type RuntimePathBacking, type RuntimePathCapabilities, type RuntimePathGuidanceVisibility, type RuntimePathLocations, type RuntimePathMapping, type RuntimePathNamespace, type RuntimePathPurpose, type RuntimePathRootMapping, type RuntimePathTranslation, type RuntimePathTranslationError, type RuntimePathTranslationErrorCode, type RuntimeVmAudience, type SecretInjectionConfig, type SplitResolvedGatewaySecretsResult, type SplitResolvedSecretsResult, type StartToolVmActiveUseRequest, type StartToolVmActiveUseResponse, TOOL_VM_SCRATCH_GUEST_ROOT, TOOL_VM_WORK_GUEST_ROOT, type ToolVmActiveUseCorrelation, type ToolVmActiveUseHandle, type ToolVmActiveUseOperationReport, type ToolVmActiveUseOutcome, type ToolVmLeaseId, type ToolVmLeasePeek, type ToolVmSshFailureKind, type ToolVmSshFailureReport, type ToolVmSshHealthOperation, type ToolVmSshLease, type ToolVmSshOperationPhase, type ToolVmSshOperationReport, type TranslateRuntimePathInput, type TranslateRuntimePathResult, type VmAudience, type VmCapabilityLease, type VmSshEndpoint, type VmSshLease, type VmSshPublicEndpoint, type WebSocketUpgradeConfig, type ZoneHealthIssue, type ZoneHealthIssueKind, type ZoneHealthSnapshot, type ZoneHealthStateKind, agentVmHealthEventKinds, agentVmHealthResultKinds, buildGatewaySessionLabel, buildToolSessionLabel, composeNodeOptions, controllerRequestPolicies, controllerVmHost, createGatewayTelemetryProducerSafetyContract, createToolVmActiveUseHandle, createToolVmActiveUseId, createToolVmLeaseId, createWebSocketUpgradeRequestGuard, defaultToolVmLeaseAuthorityTombstoneTtlMs, deriveZoneHealthSnapshot, drainControllerResponseBody, egressHostsForAudience, externalControllerRoutes, gatewayControlSessionHealthOperations, gatewayFrameworkTelemetryServiceNames, gatewayRecoveryHealthReasons, gatewayTelemetryAdmissionLimits, gatewayTelemetrySourcePolicy, gatewayToolPortalTelemetryServiceName, gatewayTypeValues, gatewayVmAllowedHosts, genericControllerRequestEventOperations, healthEventBucketKey, isAgentVmHealthEvent, isToolVmActiveUseId, isToolVmLeaseId, isToolVmLeasePeek, isToolVmSshLease, isVmCapabilityLease, isVmSshEndpoint, isVmSshPublicEndpoint, mergeRuntimeGatewaySecrets, normalizeGitHubRepoForSshReadAllowlist, normalizeGitHubReposForSshReadAllowlist, normalizeGitRepoForSshReadAllowlist, normalizeGitReposForSshReadAllowlist, normalizeToolVmActiveUseCorrelation, parseManagedGatewayBootContract, parseToolVmLeaseId, splitResolvedGatewaySecrets, splitResolvedSecretsByInjection, targetsAudience, translateRuntimePath, vmAudienceValues, websocketUpgradesForAudience, workerVmAllowedHosts, zoneHealthIssueKinds, zoneHealthStateKinds };
+//# sourceMappingURL=index.d.ts.map