beachside 0.0.0-stage → 0.8.0

package/dist/observability.d.ts

@@ -0,0 +1,64 @@
+import { SpanKind, type Context, type SpanContext, type TracerProvider } from "@opentelemetry/api";
+export interface ObservabilityOptions {
+    /** Omission uses the application provider. Beachside never owns provider shutdown. */
+    tracing?: false | {
+        tracerProvider?: TracerProvider;
+    };
+}
+export interface DiagnosticContext {
+    errorCode?: string;
+    effect?: "none" | "possible" | "applied" | "partial" | "unknown";
+    operationId?: string;
+    submissionId?: string;
+    operationState?: "pending" | "completed" | "rejected" | "failed" | "unknown";
+    recoveryAvailable: boolean;
+}
+export declare function noteRetainedResources<T extends object>(value: T, count: number): void;
+export declare function noteOperation<T extends object>(value: T, state: NonNullable<DiagnosticContext["operationState"]>, effect: DiagnosticContext["effect"]): void;
+export declare function safeIdentity(value: unknown): string | undefined;
+/** Pure correlation data; the original handle/error retains recovery authority. */
+export declare function diagnosticContext(value: unknown): Readonly<DiagnosticContext>;
+/** W3C version 00 only; fixed size, no tracestate or baggage. */
+export declare function parseTraceParent(value: unknown): SpanContext | undefined;
+export declare function activeTraceParent(): string | undefined;
+/** Internal direct SDK instrumentation; never configures OTel globals. */
+export declare class Telemetry {
+    private readonly mode;
+    private readonly provider;
+    private readonly owner;
+    constructor(options?: ObservabilityOptions, mode?: "direct", provider?: string);
+    private readonly options;
+    get enabled(): boolean;
+    correlate(value: unknown): void;
+    submitted(): void;
+    poll(state: "pending" | "completed" | "rejected" | "unknown"): void;
+    iterate(name: string, source: AsyncIterable<Uint8Array>, signal?: AbortSignal): AsyncIterable<Uint8Array>;
+    run<T>(name: string, work: () => Promise<T>, options?: {
+        phase?: boolean;
+        effect?: "none" | "possible" | "applied";
+        origin?: unknown;
+        parent?: Context;
+        kind?: SpanKind;
+        identity?: unknown;
+        operationType?: string;
+        signal?: AbortSignal;
+    }): Promise<T>;
+}
+/** Wrap an instance method; the original receiver, arguments and results are preserved. */
+export declare function instrument<T extends object, K extends keyof T>(target: T, key: K, telemetry: Telemetry, name: string, options?: {
+    phase?: boolean;
+    effect?: "none" | "possible" | "applied";
+    identity?: unknown;
+    origin?: string;
+}): void;
+/** Only explicit library delegation bypasses public tracing; user calls always get a span. */
+export declare function internalMethod<F extends (...args: never[]) => Promise<unknown>>(method: F): F;
+export declare function waitFor<T>(telemetry: Telemetry, operation: {
+    wait(options?: {
+        signal?: AbortSignal;
+        pollMs?: number;
+    }): Promise<T>;
+}, options?: {
+    signal?: AbortSignal;
+    pollMs?: number;
+}): Promise<T>;

package/dist/process-output.d.ts

@@ -0,0 +1,33 @@
+import type { ProcessOutput, ProcessOutputBytes } from "@beachside/adapter";
+export type ProcessLine = {
+    stream: "stdout" | "stderr";
+    text: string;
+    /** No newline has been observed for this line. */
+    partial: boolean;
+    /** The line exceeded its byte limit and its remainder was discarded. */
+    truncated: boolean;
+};
+export type ProcessLineOptions = {
+    maxLineBytes?: number;
+    signal?: AbortSignal;
+};
+export type ProcessTailOptions = {
+    maxBytes?: number;
+    maxChunks?: number;
+    maxLines?: number;
+    maxLineBytes?: number;
+};
+export interface ProcessTail {
+    push(chunk: ProcessOutput | ProcessOutputBytes): void;
+    /** A bounded, independent snapshot; quiet processes return immediately. */
+    snapshot(): {
+        lines: ProcessLine[];
+        truncated: boolean;
+    };
+}
+/** UTF-8 length of one code point from `for...of`; a lone surrogate encodes as U+FFFD (3 bytes). */
+export declare function utf8Length(point: string): number;
+/** Incremental UTF-8 lines, independently decoded per stream; oversized lines are clipped, not buffered. */
+export declare function readProcessLines(output: AsyncIterable<ProcessOutput | ProcessOutputBytes>, options?: ProcessLineOptions): AsyncGenerator<ProcessLine>;
+/** Keep a rolling diagnostic byte window, never a cumulative process transcript. */
+export declare function createProcessTail(options?: ProcessTailOptions): ProcessTail;

package/dist/processes.d.ts

@@ -0,0 +1,212 @@
+import { ResourceScope, type Json, type ProcessSignal, type TerminalDimensions, type NativeProcess, type Sandbox, type ProcessOutput, type ProcessOutputBytes, type ProcessOutputFormat, type NativeProcessStatus } from "@beachside/adapter";
+import { z } from "zod";
+import { BeachsideError, type ExecOutput, type ExecInput } from "./resource.js";
+import type { AdapterDirectClient } from "./adapter-direct.js";
+export type { ProcessOutput, ProcessOutputBytes, ProcessOutputFormat } from "@beachside/adapter";
+export type ProcessChunk<F extends ProcessOutputFormat> = F extends "bytes" ? ProcessOutputBytes : ProcessOutput;
+export type StartProcessInput<F extends ProcessOutputFormat = ProcessOutputFormat> = Pick<ExecInput, "command" | "cwd" | "env" | "maxOutputBytes" | "deadlineSeconds"> & {
+    stdin?: "closed" | "pipe";
+    output?: {
+        mode: "stream";
+        format?: F;
+    };
+} & (F extends "bytes" ? {
+    output: {
+        mode: "stream";
+        format: "bytes";
+    };
+} : object);
+export type { ProcessSignal, TerminalDimensions } from "@beachside/adapter";
+declare const Reference: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    provider: z.ZodString;
+    sandboxId: z.ZodString;
+    scope: z.ZodObject<{
+        authority: z.ZodObject<{
+            kind: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strict>;
+        partition: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>;
+    profile: z.ZodEnum<{
+        process: "process";
+        terminal: "terminal";
+    }>;
+    output: z.ZodEnum<{
+        bytes: "bytes";
+        text: "text";
+    }>;
+    stdin: z.ZodEnum<{
+        pipe: "pipe";
+        closed: "closed";
+    }>;
+    expiresAt: z.ZodISODateTime;
+    native: z.ZodCustom<Json, Json>;
+}, z.core.$strict>;
+export type ProcessReference<F extends ProcessOutputFormat = ProcessOutputFormat> = Omit<z.infer<typeof Reference>, "output"> & {
+    output: F;
+};
+export type StartTerminalInput = Pick<ExecInput, "command" | "cwd" | "env"> & TerminalDimensions;
+export interface TerminalHandle extends Omit<ProcessHandle<"bytes">, "output" | "closeStdin"> {
+    output(options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<Uint8Array>;
+    resize(dimensions: TerminalDimensions, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+export type ProcessTermination = {
+    status: "requested" | "not-found" | "exited";
+};
+export type ProcessExit = {
+    exitCode: number;
+    outputComplete: boolean;
+};
+export type ProcessStatus = Omit<NativeProcessStatus, "exit"> & {
+    exit?: ProcessExit;
+};
+/** Local context only; these fields cannot reopen a command. */
+export type ProcessFailure = BeachsideError & {
+    provider: string;
+    sandboxId: string;
+    confirmedExit?: ProcessExit;
+};
+export interface ProcessHandle<F extends ProcessOutputFormat = "text"> {
+    readonly provider: string;
+    readonly outputGap: boolean;
+    reference(): ProcessReference<F>;
+    signal(signal: ProcessSignal, options?: {
+        signal?: AbortSignal;
+    }): Promise<ProcessTermination>;
+    disconnect(): Promise<void>;
+    /** Returning a sustained iterator releases output only; finite legacy iterators detach the handle. */
+    output(options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<ProcessChunk<F>>;
+    wait(options?: {
+        signal?: AbortSignal;
+    }): Promise<ProcessExit>;
+    write(input: string | Uint8Array, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    closeStdin(options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    status(options?: {
+        signal?: AbortSignal;
+    }): Promise<ProcessStatus>;
+    terminate(options?: {
+        signal?: AbortSignal;
+    }): Promise<ProcessTermination>;
+    /** Dispose local IO and cancel pending local controls; never terminate the remote process. */
+    detach(): Promise<void>;
+}
+declare class LocalProcess<F extends ProcessOutputFormat> implements ProcessHandle<F> {
+    readonly provider: string;
+    private readonly sandboxId;
+    private readonly max;
+    private readonly clientSignal;
+    private readonly controlActive;
+    private readonly sustained;
+    private readonly piped;
+    private readonly format;
+    readonly outputGap: boolean;
+    private readonly referenceContext?;
+    private readonly supportedSignals;
+    native?: NativeProcess;
+    private queue;
+    private queuedBytes;
+    private total;
+    private used;
+    private stopped;
+    private finished;
+    private complete;
+    private exitCode?;
+    private failure?;
+    private detached;
+    private readonly local;
+    private waitFailure?;
+    private inputClosed;
+    private inputClosing;
+    private inputFailure?;
+    private pendingInputBytes;
+    private pendingInputCalls;
+    private inputTail;
+    private closePromise?;
+    private termination?;
+    private signalRequests;
+    private park?;
+    private resizeTail;
+    private pendingResizes;
+    private resizeFailure?;
+    private cleanupPreservesInput;
+    private savedReference?;
+    private listeners;
+    private removeOutputAbort?;
+    private readonly closed;
+    constructor(provider: string, sandboxId: string, max: number, clientSignal: AbortSignal, controlActive: () => boolean, sustained: boolean, piped: boolean, format: F, outputGap?: boolean, referenceContext?: {
+        scope: z.infer<typeof ResourceScope>;
+        profile: "process" | "terminal";
+        expiresAt: string;
+    } | undefined, supportedSignals?: readonly ProcessSignal[]);
+    get error(): BeachsideError | undefined;
+    private notify;
+    private evidence;
+    private rememberNativeExit;
+    fail(error: BeachsideError): void;
+    private releaseOutput;
+    onOutput: (value: ProcessOutput) => void;
+    onOutputBytes: (value: ProcessOutputBytes) => void;
+    attach(native: NativeProcess): void;
+    output(options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<ProcessChunk<F>>;
+    private changed;
+    wait(options?: {
+        signal?: AbortSignal;
+    }): Promise<ProcessExit>;
+    private checkInput;
+    write(input: string | Uint8Array, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    closeStdin(options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    private enqueueInput;
+    status(options?: {
+        signal?: AbortSignal;
+    }): Promise<ProcessStatus>;
+    private terminationFailure;
+    terminate(options?: {
+        signal?: AbortSignal;
+    }): Promise<ProcessTermination>;
+    private requestTermination;
+    reference(): ProcessReference<F>;
+    signal(signal: ProcessSignal, options?: {
+        signal?: AbortSignal;
+    }): Promise<ProcessTermination>;
+    private checkControl;
+    private control;
+    resize(dimensions: TerminalDimensions, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    disconnect(): Promise<void>;
+    abandonPreservingInput(): Promise<void>;
+    detach(): Promise<void>;
+}
+export declare function startProcess<F extends ProcessOutputFormat = "text">(client: AdapterDirectClient, sandbox: Sandbox, input: StartProcessInput<F>, options: {
+    signal?: AbortSignal;
+}, controlActive: () => boolean, capture?: {
+    maxBytes: number;
+}, terminal?: TerminalDimensions, reopening?: ProcessReference<F>): Promise<LocalProcess<F>>;
+export declare function reopenProcess<F extends ProcessOutputFormat>(client: AdapterDirectClient, sandbox: Sandbox, reference: ProcessReference<F>, options: {
+    signal?: AbortSignal;
+}, active: () => boolean): Promise<LocalProcess<F>>;
+export declare function terminalHandle(process: LocalProcess<"bytes">): TerminalHandle;
+export type ExecOptions = {
+    signal?: AbortSignal;
+    /** Awaited live text delivery; captured stdout/stderr remain bounded by maxOutputBytes. */
+    onOutput?: (chunk: ProcessOutput) => void | Promise<void>;
+};
+/** Exactly one process dispatch; callback failure cannot fall back to finite exec. */
+export declare function callbackExec(client: AdapterDirectClient, sandbox: Sandbox, controlActive: () => boolean, input: ExecInput | readonly string[], options: ExecOptions): Promise<ExecOutput>;

package/dist/recovery-diagnostics.d.ts

@@ -0,0 +1,10 @@
+import type { Json } from "@beachside/adapter";
+/** SDK-owned access to private state; telemetry never invokes a public accessor. */
+export declare function certifyOperationReference<T extends object>(operation: T, read: () => object): void;
+export declare function certifiedOperationReference(value: unknown): object | undefined;
+/** Called only after the SDK validates and seals its own reference copy. */
+export declare function certifyRecoveryReference<T extends object>(reference: T): T;
+/** Membership never traverses an application-provided reference or opaque token. */
+export declare function certifiedRecoveryAvailable(reference: unknown): boolean;
+/** The caller has validated JSON and enforced the reference's declared byte bound. */
+export declare function freezeRecoveryToken(value: Json): void;

package/dist/resource.d.ts

@@ -0,0 +1,175 @@
+import type { OperationOutcome } from "@beachside/adapter";
+import { SnapshotRequest, MountSpec } from "@beachside/adapter";
+import type { AdapterDirectClient, AdapterSandbox, AdapterOperation, AdapterRecoveryReference } from "./adapter-direct.js";
+import type { OperationKind, RetainedArtifact, Scope } from "@beachside/adapter";
+import { z } from "zod";
+import type { AdapterImage, AdapterSnapshot, AdapterVolume } from "./resources.js";
+import { ExecCommand, type SafeError } from "@beachside/adapter/portable";
+export type PreparedImage = {
+    kind: "prepared";
+    value: string;
+    provider: string;
+    scope: Scope;
+};
+export type ImageBuildResult = {
+    prepared: PreparedImage;
+    retainedResources: RetainedArtifact[];
+    /**
+     * The built image as a scoped reference for `images.get()` and `images.delete()`. Ownership is
+     * `verified-created` only when the adapter proved this build created it; otherwise `unknown`.
+     */
+    reference: import("@beachside/adapter").ResourceReference<"image">;
+};
+export type { OciImage, ImageInput } from "@beachside/adapter";
+import type { ImageInput, OciImage } from "@beachside/adapter";
+export declare const Image: {
+    prepared(value: string | PreparedImage): ImageInput;
+    oci(value: string): OciImage;
+};
+/** Portable outbound network policy; adapters map it to native settings. */
+export type NetworkPolicy = "blocked" | "internet" | (string & {});
+export type CreateInput = {
+    environment?: ImageInput;
+    requirements?: {
+        snapshot: SnapshotRequest;
+    };
+    mounts?: MountSpec[];
+    /** Outbound network policy; omitted uses the adapter setup default. */
+    network?: NetworkPolicy;
+    /** @deprecated Use `network`. */
+    networkPolicy?: string;
+    region?: string;
+    labels?: Record<string, string>;
+    /**
+     * Environment variables for every command, process and terminal in the sandbox,
+     * including after reopen. A per-call `env` entry overrides the same key. Values are
+     * never saved in recovery references or included in errors and telemetry.
+     */
+    env?: Record<string, string>;
+    /**
+     * Lifetime for this sandbox only, replacing the adapter setup's `lifecycle.lifetimeSeconds`.
+     * An adapter that cannot apply it exactly (or by rounding up) rejects before any effect.
+     */
+    lifecycle?: {
+        lifetimeSeconds?: number;
+    };
+};
+export type ExecInput = {
+    command: ExecCommand;
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Finite stdin bytes; strings encode as UTF-8 and supplied input ends with guest EOF. */
+    stdin?: string | Uint8Array;
+    /** Provider-specific execution/observation limit (default 300), not a total wait budget. Use the call signal to bound local waiting. */
+    deadlineSeconds?: number;
+    maxOutputBytes?: number;
+};
+export type ValidatedExecInput = Required<Pick<ExecInput, "command" | "deadlineSeconds" | "maxOutputBytes">> & Omit<ExecInput, "stdin"> & {
+    stdin?: Uint8Array;
+};
+export type OutputPreview = {
+    text: string;
+    shortened: boolean;
+};
+export type ExecOutput = {
+    exitCode: number | null;
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    truncated: boolean;
+    stdoutText(maxBytes?: number): string;
+    stdoutText(options: {
+        full: true;
+    }): string;
+    stderrText(maxBytes?: number): string;
+    stderrText(options: {
+        full: true;
+    }): string;
+    stdoutPreview(options?: {
+        maxBytes?: number;
+    }): OutputPreview;
+    stderrPreview(options?: {
+        maxBytes?: number;
+    }): OutputPreview;
+};
+export type RecoveryReference = AdapterRecoveryReference;
+/** A submitted operation; a concrete kind retains advanced continuation and narrowing. */
+export type OperationHandle<T, K extends OperationKind | undefined = undefined> = [K] extends [
+    OperationKind
+] ? AdapterOperation<T, Extract<K, OperationKind>> : {
+    readonly durability: "process";
+    readonly reference: RecoveryReference;
+    observe(): Promise<T | null>;
+    wait(options?: {
+        signal?: AbortSignal;
+        pollMs?: number;
+    }): Promise<T>;
+};
+/** @deprecated Use BeachsideClient for the complete SDK connection surface. */
+export type DirectBeachsideClient = Pick<AdapterDirectClient, "provider" | "capabilities" | "images" | "sandboxes" | "snapshots" | "volumes" | "operations" | "recover" | "close">;
+/** @deprecated Use SandboxHandle. This structural compatibility view remains available. */
+export type DirectSandboxHandle = Pick<AdapterSandbox, keyof AdapterSandbox>;
+/** Public sandbox handle. */
+export type SandboxHandle<Advanced extends boolean = false> = Advanced extends true ? AdapterSandbox : DirectSandboxHandle;
+/** Public SDK connection. */
+export type BeachsideClient<Advanced extends boolean = false> = Advanced extends true ? AdapterDirectClient : DirectBeachsideClient;
+/** A retained snapshot, with independent restore and deletion operations. */
+export type SnapshotHandle = AdapterSnapshot;
+/** A prepared image on the provider, with inspection and explicit deletion. */
+export type ImageHandle = AdapterImage;
+/** Retained storage, with explicit mount descriptors and deletion. */
+export type VolumeHandle = AdapterVolume;
+export declare class BeachsideError extends Error {
+    readonly code: string;
+    readonly effect: SafeError["effect"];
+    readonly outcome?: OperationOutcome | undefined;
+    readonly reference?: RecoveryReference | undefined;
+    constructor(code: string, message: string, effect?: SafeError["effect"], outcome?: OperationOutcome | undefined, reference?: RecoveryReference | undefined);
+}
+export declare class UnsupportedFeatureError extends BeachsideError {
+    readonly feature: string;
+    readonly unmetRequirements: readonly string[];
+    constructor(feature: string, unmetRequirements: readonly string[]);
+}
+export declare class OutcomeUnknownError<R extends RecoveryReference = RecoveryReference> extends BeachsideError {
+    readonly reference: R;
+    constructor(reference: R, message?: string, outcome?: OperationOutcome);
+}
+export declare class WaitAbortedError<R extends RecoveryReference = RecoveryReference> extends BeachsideError {
+    readonly reference: R;
+    readonly cause: unknown;
+    constructor(reference: R, reason: AbortSignal["reason"], outcome?: OperationOutcome);
+}
+export declare class NonzeroExitError extends BeachsideError {
+    readonly result: ExecOutput;
+    constructor(result: ExecOutput);
+}
+export declare class NoExitCodeError extends BeachsideError {
+    readonly result: ExecOutput;
+    constructor(result: ExecOutput);
+}
+export declare function newInvocationKey(): string;
+export declare function outputText(bytes: Uint8Array, maxBytes?: number): string;
+export declare function outputText(bytes: Uint8Array, options: {
+    full: true;
+}): string;
+export declare function validateFilePath(path: string): string;
+export declare function execOutput(exitCode: number | null, stdout: Uint8Array, stderr: Uint8Array, truncated: boolean): ExecOutput;
+export declare function checkExec(result: ExecOutput): ExecOutput;
+/** Resolves `network` (or deprecated `networkPolicy`) to the policy name an adapter declares. */
+export declare function resolveNetworkPolicy(network: string | undefined, networkPolicy: string | undefined, fallback: string, aliases?: Readonly<Record<string, string>>): string;
+export declare function validateCreate(input: CreateInput | undefined, defaultEnvironment?: ImageInput, defaultNetworkPolicy?: string, networkPolicyAliases?: Readonly<Record<string, string>>): Omit<CreateInput, "network"> & {
+    environment: ImageInput;
+    networkPolicy: string;
+};
+export declare function validateExec(input: ExecInput | readonly string[], options?: {
+    allowStdin?: boolean;
+}): ValidatedExecInput;
+export declare function waitDelay(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function throwIfAborted(signal?: AbortSignal): void;
+export declare function raceAbort<T>(work: Promise<T>, signal: AbortSignal): Promise<T>;
+/** Validate caller input only; native response validation must remain separate. */
+export declare function validateResourceInput<S extends z.ZodType>(schema: S, value: z.input<S>, message: string): z.output<S>;
+/** Options for local read-only sandbox observation. */
+export type ReadOptions = {
+    signal?: AbortSignal;
+};