@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.3-dev.fbe15023cdfe

package/dist/sandbox/runtime.d.ts

@@ -0,0 +1,297 @@
+import type { BridgeServiceConfig } from "../bridge/bridge.types.js";
+import type { SessionEventSink } from "../session/session.base.js";
+import { type RunOnceDispatchPacket, type RunOnceResultPacket } from "../session/session.types.js";
+import type { SandboxService, ValidatedSandboxContract } from "./sandbox.types.js";
+import { type RuntimeIsolationLease } from "../runtime/runtime-isolation-lease.js";
+export interface SandboxRuntime {
+    runOnce(dispatch: RunOnceDispatchPacket, sink: SessionEventSink, signal?: AbortSignal): Promise<RunOnceResultPacket>;
+    reap(options?: SandboxReapOptions): Promise<void>;
+    pendingCleanupReports?(): Promise<readonly SandboxCleanupReport[]>;
+    acknowledgeCleanupReport?(reportId: string): Promise<void>;
+    updateLease(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
+    snapshot(): SandboxRuntimeSnapshot;
+}
+export interface SandboxReapOptions {
+    readonly diskLow?: boolean;
+    readonly attemptSnapshot?: readonly SandboxAttemptSnapshot[];
+}
+export interface SandboxAttemptSnapshot {
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly status: string;
+    readonly expiresAt: string;
+}
+export interface SandboxCleanupReport {
+    readonly reportId: string;
+    readonly source: "teardown" | "reaper";
+    readonly actions: readonly SandboxCleanupAction[];
+}
+export interface SandboxCleanupAction {
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly resourceType: "container" | "network" | "volume";
+    readonly resourceId: string;
+    readonly outcome: "removed" | "failed";
+    readonly message?: string | null;
+    readonly occurredAt: string;
+}
+export interface SandboxRuntimeSnapshot {
+    readonly starting: number;
+    readonly active: number;
+    readonly degraded: number;
+}
+export interface SandboxContainerMemoryPeak {
+    readonly containerId: string;
+    readonly name: string;
+    readonly role: string;
+    readonly peakMemoryBytes: number;
+}
+export interface SandboxPeakMemoryTelemetry {
+    readonly schemaVersion: 1;
+    readonly source: "docker_stats_sampled";
+    readonly sampleIntervalMs: number;
+    readonly sampleCount: number;
+    readonly failedSampleCount: number;
+    readonly peakMemoryBytes: number;
+    readonly firstSampledAt: string;
+    readonly lastSampledAt: string;
+    readonly containers: readonly SandboxContainerMemoryPeak[];
+}
+export interface DockerStatsMemorySample {
+    readonly containerId: string;
+    readonly name: string;
+    readonly memoryBytes: number;
+}
+export interface SandboxPublicationGrantRequest {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly grantId: string;
+    readonly branch: string;
+    readonly resultCommitSha: string;
+}
+export interface SandboxPublicationCredential {
+    readonly username: string;
+    readonly secret: string;
+    readonly remoteUrl: string;
+    readonly expiresAt: string;
+}
+export type SandboxPublicationGrantRedeemer = (request: SandboxPublicationGrantRequest, signal?: AbortSignal) => Promise<SandboxPublicationCredential>;
+export declare class DockerSandboxRuntime implements SandboxRuntime {
+    private readonly config;
+    private readonly publicationGrantRedeemer?;
+    private readonly active;
+    private readonly degraded;
+    private readonly builds;
+    private readonly verifiedCatalogImages;
+    private buildTail;
+    constructor(config: BridgeServiceConfig, publicationGrantRedeemer?: SandboxPublicationGrantRedeemer | undefined);
+    runOnce(dispatch: RunOnceDispatchPacket, sink: SessionEventSink, signal?: AbortSignal): Promise<RunOnceResultPacket>;
+    updateLease(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
+    private pushLeaseUpdate;
+    snapshot(): SandboxRuntimeSnapshot;
+    reap(options?: SandboxReapOptions): Promise<void>;
+    pendingCleanupReports(): Promise<readonly SandboxCleanupReport[]>;
+    acknowledgeCleanupReport(reportId: string): Promise<void>;
+    private persistCleanupReport;
+    private cleanupReportPath;
+    private writeLedger;
+    private readLedgers;
+    private ledgerPath;
+    private removeLedger;
+    private buildImage;
+    private withBuildPermit;
+    private buildImageCore;
+    private runBuildStage;
+    private ensureBuildxBuilder;
+    private stopBuildxBuilder;
+    private initializeVolumes;
+    private inspectContainerState;
+    private initializeServiceSecrets;
+    private initializeProviderCredentials;
+    private initializeEgressPolicy;
+    private startEgressProxy;
+    private startServices;
+    private verifyCatalogImage;
+    private waitForServiceHealthy;
+    private teardown;
+    private listResources;
+    private inspectResourceLabels;
+    private removeResource;
+    private writeImageCacheRecord;
+    private readImageCacheRecords;
+    private readImageCacheRecord;
+    private collectExpiredImages;
+    private purgeRestrictedAuditArtifacts;
+    private inspectImageMetadata;
+    private startPeakMemorySampler;
+    private docker;
+    private dockerArgs;
+}
+export declare function managedBranchUpdateExpectedValue(current: string, expectedInput: string, imported: string): string;
+export declare function publicationPushArgs(branch: string, resultCommitSha: string, inputCommitSha: string, remoteCommitSha: string, remote?: string): string[] | null;
+export declare function validatePublicationCredential(credential: SandboxPublicationCredential, nowMs?: number): void;
+export declare function publicationCredentialEnvironment(credential: SandboxPublicationCredential, environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export interface RestrictedBuildLog {
+    readonly content: string;
+    readonly digest: string;
+    readonly byteCount: number;
+    readonly truncated: boolean;
+}
+export declare function restrictedBuildLog(source: string, exactSecrets?: readonly string[], maximumBytes?: number): RestrictedBuildLog;
+export declare function validateGitObjectBudget(inventory: string, maximumObjectCount?: number, maximumExpandedBytes?: number): {
+    readonly objectCount: number;
+    readonly expandedBytes: number;
+};
+export declare function validateGitCommitDepth(value: string, maximumCommitDepth?: number): number;
+export interface AuditArtifactRecord {
+    readonly key: string;
+    readonly lastModifiedMs: number;
+}
+export declare function selectAuditArtifactGcCandidates(records: readonly AuditArtifactRecord[], retentionCount: number, retentionTtlMs: number, protectedKeys?: ReadonlySet<string>, nowMs?: number): string[];
+export declare function selectSandboxConfigRefs(executionPolicy: string, configuredSha: string | null | undefined, defaultBranch: string): {
+    readonly refs: readonly string[];
+    readonly approvedSha: string | null;
+};
+export declare function selectSandboxInputRefs(worktreeKey: string, baseBranch: string): readonly string[];
+export declare function sandboxTimeLimits(environment?: NodeJS.ProcessEnv): {
+    readonly hardWallMs: number;
+    readonly idleMs: number;
+};
+export interface ImageCacheRecord {
+    readonly schemaVersion: 1;
+    readonly key: string;
+    readonly project: string;
+    readonly createdAt: string;
+    readonly lastUsedAt: string;
+    readonly projectTag: string;
+    readonly helperTag: string;
+    readonly overlayTag: string;
+    readonly imageDigest: string;
+    readonly helperImageDigest: string;
+    readonly bridgeRuntimeDigest?: string;
+    readonly policyDigest: string;
+}
+export declare function sandboxWorkerFailureMessage(exitCode: number, stderr: string, containerError: string | null): string;
+interface ResourceNames {
+    prefix: string;
+    container: string;
+    network: string;
+    egressNetwork: string;
+    workspaceVolume: string;
+    controlVolume: string;
+    secretsVolume: string;
+    credentialsVolume: string;
+    egressConfigVolume: string;
+    cacheVolumes: Record<string, string>;
+}
+interface SandboxRuntimeVolume {
+    readonly name: string;
+    readonly role: string;
+}
+export declare function parseDockerMemoryBytes(value: string): number | null;
+export declare function parseDockerStatsMemorySample(output: string): DockerStatsMemorySample[];
+interface ActiveSandbox {
+    dispatchAttemptId: string;
+    fencingToken: string;
+    expiresAt: string;
+    controller: AbortController;
+    phase: "starting" | "active";
+    runtimeLease: RuntimeIsolationLease;
+    ledger: SandboxLedger | null;
+    leaseControlKey: string;
+}
+export declare function assertSandboxImportCurrent(expected: Pick<ActiveSandbox, "dispatchAttemptId" | "fencingToken" | "expiresAt">, current: Pick<ActiveSandbox, "dispatchAttemptId" | "fencingToken"> | undefined, signal: AbortSignal, nowMs?: number): void;
+interface SandboxLedger {
+    schemaVersion: 3;
+    runtimeLease: RuntimeIsolationLease;
+    resources: ResourceNames;
+    labels: Record<string, string>;
+    includeCredentials?: boolean;
+    peakMemory?: SandboxPeakMemoryTelemetry;
+}
+interface LegacySandboxLedger {
+    schemaVersion: 2;
+    resourceLeaseId: string;
+    dispatchAttemptId: string;
+    fencingToken: string;
+    runnerInstanceId: string;
+    expiresAt: string;
+    resources: ResourceNames;
+    labels: Record<string, string>;
+    includeCredentials?: boolean;
+    peakMemory?: SandboxPeakMemoryTelemetry;
+}
+export declare function validSandboxLedger(value: unknown): boolean;
+export declare function normalizeSandboxLedger(value: unknown): SandboxLedger | null;
+export declare function resourceNames(attemptHex: string, perAttemptCaches?: readonly string[]): ResourceNames;
+export declare function dockerObjectId(output: string, kind: "container" | "network"): string;
+export declare function sandboxRuntimeVolumes(resources: ResourceNames, includeEgressPolicy?: boolean, includeCredentials?: boolean): SandboxRuntimeVolume[];
+export declare function sandboxRuntimeCleanupVolumeNames(resources: ResourceNames, includeCredentials?: boolean): string[];
+export declare function sandboxResourceLabels(dispatch: RunOnceDispatchPacket, image: string, contract: string): Record<string, string>;
+export declare function mayReapManagedResource(labels: Readonly<Record<string, string>>, runnerId: string, liveAttempts: ReadonlySet<string>): boolean;
+export declare function shouldReapSandboxLedger(ledger: Readonly<Pick<SandboxLedger, "runtimeLease">> | Readonly<Pick<LegacySandboxLedger, "dispatchAttemptId" | "fencingToken" | "runnerInstanceId" | "expiresAt">>, currentRunnerInstanceId: string, serverAttempt: SandboxAttemptSnapshot | undefined, snapshotAvailable: boolean, nowMs?: number): boolean;
+export declare function bridgeRuntimeCacheMatches(record: Pick<ImageCacheRecord, "bridgeRuntimeDigest"> | null | undefined, expectedDigest: string, imageLabels: readonly (Readonly<Record<string, string>> | null | undefined)[]): boolean;
+export declare function prepareOverlayBuildRoot(overlayRoot: string): Promise<void>;
+export declare function extractOciLayoutArchive(archivePath: string, destination: string, signal?: AbortSignal): Promise<void>;
+export declare function ociLayoutContextRef(layoutPath: string): string;
+export declare function formatOciExtractionFailure(result: {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly truncated: boolean;
+}): string;
+export declare function readOciLayoutImageDigest(layoutRoot: string): Promise<string>;
+export declare function removeExtractedOciLayout(layoutRoot: string): Promise<void>;
+export declare function ociLayoutScanTarget(layoutPath: string): string;
+export declare function agentOverlayDockerignore(): string;
+export interface SandboxImageCacheKeyInput {
+    readonly contextDigest: string;
+    readonly contractDigest: string;
+    readonly platform: string;
+    readonly architecture: string;
+    readonly bridgeVersion: string;
+    readonly bridgeRuntimeDigest: string;
+    readonly toolingImage: string;
+    readonly codexVersion: string;
+    readonly policy: string;
+    readonly policyConfigurationDigest: string;
+}
+export declare function sandboxImageCacheKey(input: SandboxImageCacheKeyInput): string;
+export declare function bridgeRuntimeContentDigest(packageRoot: string): Promise<string>;
+export declare function agentOverlayDockerfile(toolingImage: string, projectContextName: string, installMode: BridgePackageInstallMode, codexVersion: string): string;
+export type BridgePackageInstallMode = "ci" | "install";
+export declare function copyBridgePackageManifests(packageRoot: string, bridgeRoot: string): Promise<BridgePackageInstallMode>;
+export declare function bridgePackageInstallCommand(mode: BridgePackageInstallMode, codexVersion: string): string;
+export declare function buildxBuildArgs(builder: string, metadataFile: string, tail: readonly string[], environment?: NodeJS.ProcessEnv, options?: {
+    readonly load?: boolean;
+}): string[];
+export declare function buildResourcePolicy(environment?: NodeJS.ProcessEnv): {
+    readonly nofile: number;
+    readonly sharedMemory: string;
+    readonly builderPidsLimit: number;
+    readonly builderMemoryBytes: number;
+};
+export declare function dedicatedBuildxBuilderName(runnerId: string, dockerContext: string | null | undefined): string;
+export declare function dedicatedBuildxBuilderContainerName(builder: string): string;
+export declare function selectImageGcCandidates(records: readonly ImageCacheRecord[], keepPerProject: number, ttlMs: number, nowMs: number): ImageCacheRecord[];
+export declare function workerCreateArgs(dispatch: RunOnceDispatchPacket, contract: ValidatedSandboxContract, resources: ResourceNames, labels: Record<string, string>, image: string, securityOptions?: readonly string[]): string[];
+export declare function validateSandboxMemoryReservation(dispatch: RunOnceDispatchPacket, contract: ValidatedSandboxContract): void;
+export declare function cacheVolumeArgs(contract: ValidatedSandboxContract, resources: ResourceNames): string[];
+export declare function proxyEnvironmentArgs(dispatch: RunOnceDispatchPacket, contract: ValidatedSandboxContract, resources: ResourceNames): string[];
+export declare function egressProxyConfig(allowedHosts: readonly string[]): string;
+export declare function serviceContainerArgs(service: SandboxService, image: string, resources: ResourceNames, labels: Record<string, string>, securityOptions: readonly string[], environment?: NodeJS.ProcessEnv): string[];
+export declare function resolveSandboxSecurityOptions(executionPolicy: string, environment?: NodeJS.ProcessEnv): string[];
+export declare function networkCreateArgs(dispatch: RunOnceDispatchPacket, environment?: NodeJS.ProcessEnv, allowOpenPublicSandbox?: boolean): string[];
+export declare function classifySandboxRuntimeFailure(value: string): {
+    readonly code: string;
+    readonly phase: string;
+    readonly message: string;
+};
+export declare function classifySandboxResourceFailure(value: string): {
+    readonly code: string;
+    readonly message: string;
+} | null;
+export {};