@sandbox-kit/sandbox 0.0.0-stage → 0.1.0

package/dist/contracts/sandbox_data_contracts.d.ts

@@ -0,0 +1,203 @@
+import type { DurationFieldsToMs } from "#internal/duration_ms.js";
+import type { EmptyMarkersAsTrue, FlattenAllowlistFields, PlainStringMapFields, RemapFields } from "#internal/input_remap.js";
+import type { StripProto } from "#internal/strip_proto.js";
+import { EgressMode as ProtoEgressMode, IsolationKind as ProtoIsolationKind, LifecycleCapability as ProtoLifecycleCapability, PolicyMode as ProtoPolicyMode, PortTransport as ProtoPortTransport, SandboxState as ProtoSandboxState, SecretInjection as ProtoSecretInjection, SnapshotKind as ProtoSnapshotKind, ValueOrigin as ProtoValueOrigin, WaitCondition as ProtoWaitCondition, type ArchiveOptions as ProtoArchiveOptions, type CreateOptions as ProtoCreateOptions, type CreateResult as ProtoCreateResult, type DeleteOptions as ProtoDeleteOptions, type ErrorInfo as ProtoErrorInfo, type ExitResult as ProtoExitResult, type IsolationConfig as ProtoIsolationConfig, type MetadataList as ProtoMetadataList, type MetadataObject as ProtoMetadataObject, type MetadataValue as ProtoMetadataValue, type ObservabilityConfig as ProtoObservabilityConfig, type PauseOptions as ProtoPauseOptions, type Placement as ProtoPlacement, type PortBinding as ProtoPortBinding, type Resources as ProtoResources, type RuntimeConfig as ProtoRuntimeConfig, type SandboxInfo as ProtoSandboxInfo, type SandboxSource as ProtoSandboxSource, type SecretReference as ProtoSecretReference, type SecurityConfig as ProtoSecurityConfig, type StartOptions as ProtoStartOptions, type StopOptions as ProtoStopOptions, type TerminateOptions as ProtoTerminateOptions, type ReadinessProbe as ProtoReadinessProbe } from "@sandbox-kit/contracts/sandbox";
+import type { StripAndFlatten } from "#internal/oneof_input.js";
+import type { MetadataPlain } from "#metadata/metadata_plain.js";
+/** Public error payload; identity fields stay required after StripProto softening. */
+export type ErrorInfo = StripProto<ProtoErrorInfo> & {
+    kind: NonNullable<StripProto<ProtoErrorInfo>["kind"]>;
+    provider: string;
+    operation: string;
+    field: string;
+    message: string;
+};
+export type RuntimeConfig = StripProto<ProtoRuntimeConfig>;
+export type IsolationConfig = StripProto<ProtoIsolationConfig>;
+export type Resources = StripProto<ProtoResources>;
+export type Placement = StripProto<ProtoPlacement>;
+export type PortBinding = StripProto<ProtoPortBinding>;
+export type SecurityConfig = StripProto<ProtoSecurityConfig>;
+export type SecretReference = StripProto<ProtoSecretReference>;
+export type ObservabilityConfig = StripProto<ProtoObservabilityConfig>;
+export type SandboxInfo = StripProto<ProtoSandboxInfo>;
+export type CreateResult = StripProto<ProtoCreateResult>;
+/** Wire lifecycle options (Duration timeouts) for providers / Backend. */
+export type StartOptions = StripProto<ProtoStartOptions>;
+export type StopOptions = StripProto<ProtoStopOptions>;
+export type PauseOptions = StripProto<ProtoPauseOptions>;
+export type TerminateOptions = StripProto<ProtoTerminateOptions>;
+export type ArchiveOptions = StripProto<ProtoArchiveOptions>;
+export type DeleteOptions = StripProto<ProtoDeleteOptions>;
+export type ExitResult = StripProto<ProtoExitResult>;
+export type MetadataValue = StripProto<ProtoMetadataValue>;
+export type MetadataList = StripProto<ProtoMetadataList>;
+export type MetadataObject = StripProto<ProtoMetadataObject>;
+/**
+ * Public create request for `Client.create`.
+ * Composed from reusable input transforms: strip + flatten oneofs → plain maps /
+ * allowlists / empty markers → ms durations.
+ */
+export type CreateOptions = DurationFieldsToMs<EmptyMarkersAsTrue<FlattenAllowlistFields<PlainStringMapFields<RemapFields<StripAndFlatten<ProtoCreateOptions, {
+    source: NonNullable<ProtoSandboxSource["kind"]>;
+    readiness: NonNullable<ProtoReadinessProbe["check"]>;
+}>, {
+    providerOptions: Record<string, MetadataPlain>;
+}>>>>>;
+/**
+ * Public network create input (allowlists are plain `string[]`).
+ * Derived from {@link CreateOptions}; present empty arrays mean deny-all.
+ */
+export type NetworkConfigInput = NonNullable<CreateOptions["network"]>;
+/** Public create source: set exactly one variant (no protobuf `{ case, value }`). */
+export type SandboxSourceInput = NonNullable<CreateOptions["source"]>;
+/** Public readiness: set tcpPort or command (no protobuf `{ case, value }`). */
+export type ReadinessProbeInput = NonNullable<CreateOptions["readiness"]>;
+/**
+ * Public lifetime create input (ms durations).
+ * Derived from {@link CreateOptions}; wire `Duration` fields stay private.
+ */
+export type LifetimePolicyInput = NonNullable<CreateOptions["lifetime"]>;
+/**
+ * Public idle/stopped policy leaf under {@link LifetimePolicyInput} (`after` in ms).
+ */
+export type AutomaticActionInput = NonNullable<LifetimePolicyInput["idleTerminate"]>;
+/**
+ * Public provisioning create input (ms timeouts).
+ * Derived from {@link CreateOptions}; wire `Duration` fields stay private.
+ */
+export type ProvisioningOptionsInput = NonNullable<CreateOptions["provisioning"]>;
+export declare const SnapshotKind: {
+    readonly Default: ProtoSnapshotKind.DEFAULT;
+    readonly Filesystem: ProtoSnapshotKind.FILESYSTEM;
+    readonly Memory: ProtoSnapshotKind.MEMORY;
+    readonly Image: ProtoSnapshotKind.IMAGE;
+    readonly Machine: ProtoSnapshotKind.MACHINE;
+    readonly Checkpoint: ProtoSnapshotKind.CHECKPOINT;
+    readonly ProviderSpecific: ProtoSnapshotKind.PROVIDER_SPECIFIC;
+};
+export type SnapshotKind = (typeof SnapshotKind)[keyof typeof SnapshotKind];
+export declare const SnapshotKindNumber: {
+    readonly Default: ProtoSnapshotKind.DEFAULT;
+    readonly Filesystem: ProtoSnapshotKind.FILESYSTEM;
+    readonly Memory: ProtoSnapshotKind.MEMORY;
+    readonly Image: ProtoSnapshotKind.IMAGE;
+    readonly Machine: ProtoSnapshotKind.MACHINE;
+    readonly Checkpoint: ProtoSnapshotKind.CHECKPOINT;
+    readonly ProviderSpecific: ProtoSnapshotKind.PROVIDER_SPECIFIC;
+};
+export declare const IsolationKind: {
+    readonly Default: ProtoIsolationKind.DEFAULT;
+    readonly ProviderSpecific: ProtoIsolationKind.PROVIDER_SPECIFIC;
+    readonly Container: ProtoIsolationKind.CONTAINER;
+    readonly Microvm: ProtoIsolationKind.MICROVM;
+    readonly LinuxVm: ProtoIsolationKind.LINUX_VM;
+    readonly Worker: ProtoIsolationKind.WORKER;
+};
+export type IsolationKind = (typeof IsolationKind)[keyof typeof IsolationKind];
+export declare const IsolationKindNumber: {
+    readonly Default: ProtoIsolationKind.DEFAULT;
+    readonly ProviderSpecific: ProtoIsolationKind.PROVIDER_SPECIFIC;
+    readonly Container: ProtoIsolationKind.CONTAINER;
+    readonly Microvm: ProtoIsolationKind.MICROVM;
+    readonly LinuxVm: ProtoIsolationKind.LINUX_VM;
+    readonly Worker: ProtoIsolationKind.WORKER;
+};
+export declare const EgressMode: {
+    readonly Default: ProtoEgressMode.DEFAULT;
+    readonly AllowAll: ProtoEgressMode.ALLOW_ALL;
+    readonly BlockAll: ProtoEgressMode.BLOCK_ALL;
+    readonly Restricted: ProtoEgressMode.RESTRICTED;
+};
+export type EgressMode = (typeof EgressMode)[keyof typeof EgressMode];
+export declare const EgressModeNumber: {
+    readonly Default: ProtoEgressMode.DEFAULT;
+    readonly AllowAll: ProtoEgressMode.ALLOW_ALL;
+    readonly BlockAll: ProtoEgressMode.BLOCK_ALL;
+    readonly Restricted: ProtoEgressMode.RESTRICTED;
+};
+export declare const PortTransport: {
+    readonly Default: ProtoPortTransport.DEFAULT;
+    readonly Tls: ProtoPortTransport.TLS;
+    readonly Http2Tls: ProtoPortTransport.HTTP2_TLS;
+    readonly Plain: ProtoPortTransport.PLAIN;
+};
+export type PortTransport = (typeof PortTransport)[keyof typeof PortTransport];
+export declare const PortTransportNumber: {
+    readonly Default: ProtoPortTransport.DEFAULT;
+    readonly Tls: ProtoPortTransport.TLS;
+    readonly Http2Tls: ProtoPortTransport.HTTP2_TLS;
+    readonly Plain: ProtoPortTransport.PLAIN;
+};
+export declare const SecretInjection: {
+    readonly Default: ProtoSecretInjection.DEFAULT;
+    readonly Environment: ProtoSecretInjection.ENVIRONMENT;
+    readonly EgressPlaceholder: ProtoSecretInjection.EGRESS_PLACEHOLDER;
+};
+export type SecretInjection = (typeof SecretInjection)[keyof typeof SecretInjection];
+export declare const SecretInjectionNumber: {
+    readonly Default: ProtoSecretInjection.DEFAULT;
+    readonly Environment: ProtoSecretInjection.ENVIRONMENT;
+    readonly EgressPlaceholder: ProtoSecretInjection.EGRESS_PLACEHOLDER;
+};
+export declare const PolicyMode: {
+    readonly Default: ProtoPolicyMode.DEFAULT;
+    readonly Disabled: ProtoPolicyMode.DISABLED;
+    readonly After: ProtoPolicyMode.AFTER;
+};
+export type PolicyMode = (typeof PolicyMode)[keyof typeof PolicyMode];
+export declare const PolicyModeNumber: {
+    readonly Default: ProtoPolicyMode.DEFAULT;
+    readonly Disabled: ProtoPolicyMode.DISABLED;
+    readonly After: ProtoPolicyMode.AFTER;
+};
+export declare const WaitCondition: {
+    readonly Default: ProtoWaitCondition.DEFAULT;
+    readonly Submitted: ProtoWaitCondition.SUBMITTED;
+    readonly Scheduled: ProtoWaitCondition.SCHEDULED;
+    readonly Started: ProtoWaitCondition.STARTED;
+    readonly Ready: ProtoWaitCondition.READY;
+};
+export type WaitCondition = (typeof WaitCondition)[keyof typeof WaitCondition];
+export declare const WaitConditionNumber: {
+    readonly Default: ProtoWaitCondition.DEFAULT;
+    readonly Submitted: ProtoWaitCondition.SUBMITTED;
+    readonly Scheduled: ProtoWaitCondition.SCHEDULED;
+    readonly Started: ProtoWaitCondition.STARTED;
+    readonly Ready: ProtoWaitCondition.READY;
+};
+export declare const SandboxState: {
+    readonly Unknown: ProtoSandboxState.UNKNOWN;
+    readonly Queued: ProtoSandboxState.QUEUED;
+    readonly Starting: ProtoSandboxState.STARTING;
+    readonly Running: ProtoSandboxState.RUNNING;
+    readonly Stopping: ProtoSandboxState.STOPPING;
+    readonly Stopped: ProtoSandboxState.STOPPED;
+    readonly Pausing: ProtoSandboxState.PAUSING;
+    readonly Paused: ProtoSandboxState.PAUSED;
+    readonly Archiving: ProtoSandboxState.ARCHIVING;
+    readonly Archived: ProtoSandboxState.ARCHIVED;
+    readonly Terminating: ProtoSandboxState.TERMINATING;
+    readonly Terminated: ProtoSandboxState.TERMINATED;
+    readonly Deleting: ProtoSandboxState.DELETING;
+    readonly Deleted: ProtoSandboxState.DELETED;
+    readonly Error: ProtoSandboxState.ERROR;
+};
+export type SandboxState = (typeof SandboxState)[keyof typeof SandboxState];
+export declare const LifecycleCapability: {
+    readonly Unknown: ProtoLifecycleCapability.UNKNOWN;
+    readonly Refresh: ProtoLifecycleCapability.REFRESH;
+    readonly Start: ProtoLifecycleCapability.START;
+    readonly Stop: ProtoLifecycleCapability.STOP;
+    readonly Pause: ProtoLifecycleCapability.PAUSE;
+    readonly Terminate: ProtoLifecycleCapability.TERMINATE;
+    readonly Archive: ProtoLifecycleCapability.ARCHIVE;
+    readonly Delete: ProtoLifecycleCapability.DELETE;
+};
+export type LifecycleCapability = (typeof LifecycleCapability)[keyof typeof LifecycleCapability];
+export declare const ValueOrigin: {
+    readonly Provider: ProtoValueOrigin.PROVIDER;
+    readonly Unknown: ProtoValueOrigin.UNKNOWN;
+    readonly Request: ProtoValueOrigin.REQUEST;
+};
+export type ValueOrigin = (typeof ValueOrigin)[keyof typeof ValueOrigin];

package/dist/contracts/sandbox_data_contracts.js

@@ -0,0 +1,22 @@
+// Portable sandbox data contracts come from standard protobuf generation.
+// These aliases keep the SDK entrypoint concise while ensuring one representation.
+import { EgressMode as ProtoEgressMode, IsolationKind as ProtoIsolationKind, LifecycleCapability as ProtoLifecycleCapability, PolicyMode as ProtoPolicyMode, PortTransport as ProtoPortTransport, SandboxState as ProtoSandboxState, SecretInjection as ProtoSecretInjection, SnapshotKind as ProtoSnapshotKind, ValueOrigin as ProtoValueOrigin, WaitCondition as ProtoWaitCondition, } from "@sandbox-kit/contracts/sandbox";
+import { protoEnum } from "#internal/proto_enum.js";
+// Ergonomic PascalCase names over protobuf enum values; not a second contract.
+export const SnapshotKind = protoEnum(ProtoSnapshotKind);
+export const SnapshotKindNumber = SnapshotKind;
+export const IsolationKind = protoEnum(ProtoIsolationKind);
+export const IsolationKindNumber = IsolationKind;
+export const EgressMode = protoEnum(ProtoEgressMode);
+export const EgressModeNumber = EgressMode;
+export const PortTransport = protoEnum(ProtoPortTransport);
+export const PortTransportNumber = PortTransport;
+export const SecretInjection = protoEnum(ProtoSecretInjection);
+export const SecretInjectionNumber = SecretInjection;
+export const PolicyMode = protoEnum(ProtoPolicyMode);
+export const PolicyModeNumber = PolicyMode;
+export const WaitCondition = protoEnum(ProtoWaitCondition);
+export const WaitConditionNumber = WaitCondition;
+export const SandboxState = protoEnum(ProtoSandboxState);
+export const LifecycleCapability = protoEnum(ProtoLifecycleCapability);
+export const ValueOrigin = protoEnum(ProtoValueOrigin);

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "#contracts/sandbox_data_contracts.js";
+export * from "#contracts/field_paths.js";
+export * from "#contracts/config_paths.js";
+export * from "#metadata/metadata_object.js";
+export * from "#client/client.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "#contracts/sandbox_data_contracts.js";
+export * from "#contracts/field_paths.js";
+export * from "#contracts/config_paths.js";
+export * from "#metadata/metadata_object.js";
+export * from "#client/client.js";

package/dist/internal/duration_ms.d.ts

@@ -0,0 +1,15 @@
+import { type Duration } from "@bufbuild/protobuf/wkt";
+/** True when a value looks like a protobuf Duration message or init. */
+export declare function isDurationValue(value: unknown): value is Duration;
+type DurationFieldName = "timeout" | "queueTimeout" | "maximumLifetime" | "after";
+/**
+ * Recursively replace known protobuf Duration fields with millisecond numbers
+ * for public request construction. Field-name based so maps like `labels` are
+ * left alone. Public values are always milliseconds.
+ */
+export type DurationFieldsToMs<T> = T extends readonly (infer U)[] ? DurationFieldsToMs<U>[] : T extends object ? {
+    [K in keyof T]: K extends DurationFieldName ? undefined extends T[K] ? number | undefined : number : DurationFieldsToMs<T[K]>;
+} : T;
+/** Convert public ms numbers on known duration fields into protobuf Durations. */
+export declare function materializeDurationFields<T>(value: T): T;
+export {};

package/dist/internal/duration_ms.js

@@ -0,0 +1,41 @@
+import { durationFromMs } from "@bufbuild/protobuf/wkt";
+/** True when a value looks like a protobuf Duration message or init. */
+export function isDurationValue(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        ("seconds" in value || "nanos" in value) &&
+        !Array.isArray(value));
+}
+const durationFieldNames = new Set([
+    "timeout",
+    "queueTimeout",
+    "maximumLifetime",
+    "after",
+]);
+/** Convert public ms numbers on known duration fields into protobuf Durations. */
+export function materializeDurationFields(value) {
+    return materializeDurationFieldsAt(value, []);
+}
+function materializeDurationFieldsAt(value, path) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "number") {
+        const leaf = path[path.length - 1];
+        if (leaf !== undefined && durationFieldNames.has(leaf)) {
+            return durationFromMs(value);
+        }
+        return value;
+    }
+    if (typeof value !== "object")
+        return value;
+    if (isDurationValue(value))
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((item) => materializeDurationFieldsAt(item, path));
+    }
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        out[key] = materializeDurationFieldsAt(child, [...path, key]);
+    }
+    return out;
+}

package/dist/internal/input_remap.d.ts

@@ -0,0 +1,36 @@
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type PreserveOptional<Orig, New> = undefined extends Orig ? New | undefined : New;
+/**
+ * Replace selected fields with R[K], keeping each field's optionality from T.
+ * Prefer this over call-site `Omit<T, K> & { K?: New }`. Keys in R that are
+ * absent from T are ignored; only overlapping keys are rewritten.
+ */
+export type RemapFields<T, R> = Simplify<{
+    [K in keyof T]: K extends keyof R ? PreserveOptional<T[K], R[K]> : T[K];
+}>;
+type AllowlistField = "outboundCidrs" | "outboundDomains" | "inboundCidrs";
+/**
+ * Recursively unwrap StringAllowlist-shaped fields to plain `string[]`.
+ * Present empty arrays still mean deny-all after materialize.
+ */
+export type FlattenAllowlistFields<T> = T extends readonly (infer U)[] ? FlattenAllowlistFields<U>[] : T extends object ? {
+    [K in keyof T]: K extends AllowlistField ? PreserveOptional<T[K], string[]> : FlattenAllowlistFields<T[K]>;
+} : T;
+type EmptyMarkerField = "providerDefault";
+/**
+ * Recursively turn empty wire marker messages into `true` presence flags
+ * (e.g. `source.providerDefault?: true`).
+ */
+export type EmptyMarkersAsTrue<T> = T extends readonly (infer U)[] ? EmptyMarkersAsTrue<U>[] : T extends object ? {
+    [K in keyof T]: K extends EmptyMarkerField ? PreserveOptional<T[K], true> : EmptyMarkersAsTrue<T[K]>;
+} : T;
+type StringMapField = "environment" | "labels";
+/**
+ * Recursively replace noisy proto string maps with `Record<string, string>`.
+ */
+export type PlainStringMapFields<T> = T extends readonly (infer U)[] ? PlainStringMapFields<U>[] : T extends object ? {
+    [K in keyof T]: K extends StringMapField ? PreserveOptional<T[K], Record<string, string>> : PlainStringMapFields<T[K]>;
+} : T;
+export {};

package/dist/internal/input_remap.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/oneof_input.d.ts

@@ -0,0 +1,32 @@
+import type { RemapFields } from "./input_remap.js";
+import type { StripProto } from "./strip_proto.js";
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type ProtoOneof = {
+    case: string | undefined;
+    value?: unknown;
+};
+/**
+ * Derive nested exclusive input fields from a protobuf-es `{ case, value }` oneof.
+ * Variant payloads are StripProto'd (no `$typeName` / `$unknown`).
+ */
+export type FlattenOneof<T extends ProtoOneof> = Simplify<{
+    [K in Exclude<T["case"], undefined>]?: StripProto<Exclude<Extract<T, {
+        case: K;
+    }>["value"], undefined>>;
+}>;
+/**
+ * Strip protobuf-es internals, then replace listed fields with flattened oneof
+ * bags. Use when a wire field is a carrier message whose oneof should surface
+ * as exclusive keys on the public input (e.g. `source.kind` → `source.image`).
+ *
+ * `Oneofs` maps each remapped field to the oneof union to flatten.
+ * Further public remaps (allowlists, ms durations, plain maps) compose outside.
+ */
+export type StripAndFlatten<T, Oneofs extends {
+    [K in keyof Oneofs]: K extends keyof T ? ProtoOneof : never;
+}> = RemapFields<StripProto<T>, {
+    [K in keyof Oneofs & string]: FlattenOneof<Oneofs[K]>;
+}>;
+export {};

package/dist/internal/oneof_input.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/proto_enum.d.ts

@@ -0,0 +1,25 @@
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** `ALLOW_ALL` → `AllowAll`, `HTTP2_TLS` → `Http2Tls`. */
+type SnakeToPascal<S extends string> = S extends `${infer Head}_${infer Tail}` ? `${Capitalize<Lowercase<Head>>}${SnakeToPascal<Tail>}` : Capitalize<Lowercase<S>>;
+/** Forward protobuf-es enum member names (skip reverse numeric keys). */
+type EnumMemberKeys<E> = {
+    [K in keyof E]: K extends string ? E[K] extends number ? K extends `${number}` ? never : K : never : never;
+}[keyof E];
+/**
+ * Public const object for a protobuf-es enum: PascalCase keys, same numeric
+ * values. Does not invent a second contract — only renames member keys.
+ */
+export type EnumConst<E> = Simplify<{
+    readonly [K in EnumMemberKeys<E> as SnakeToPascal<K & string>]: E[K];
+}>;
+/**
+ * Build an ergonomic enum const from a protobuf-es numeric enum object.
+ *
+ * @example
+ * export const EgressMode = protoEnum(ProtoEgressMode);
+ * // { Default: 0, AllowAll: 1, BlockAll: 2, Restricted: 3 }
+ */
+export declare function protoEnum<E extends Record<string, string | number>>(proto: E): EnumConst<E>;
+export {};

package/dist/internal/proto_enum.js

@@ -0,0 +1,25 @@
+function snakeToPascal(name) {
+    return name
+        .toLowerCase()
+        .split("_")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+}
+/**
+ * Build an ergonomic enum const from a protobuf-es numeric enum object.
+ *
+ * @example
+ * export const EgressMode = protoEnum(ProtoEgressMode);
+ * // { Default: 0, AllowAll: 1, BlockAll: 2, Restricted: 3 }
+ */
+export function protoEnum(proto) {
+    const out = {};
+    for (const [key, value] of Object.entries(proto)) {
+        if (typeof value !== "number")
+            continue;
+        if (/^\d+$/.test(key))
+            continue;
+        out[snakeToPascal(key)] = value;
+    }
+    return out;
+}

package/dist/internal/strip_proto.d.ts

@@ -0,0 +1,46 @@
+import type { Duration, Timestamp } from "@bufbuild/protobuf/wkt";
+type ProtoKey = "$typeName" | "$unknown";
+/**
+ * True for proto3 map fields (`{ [key: string]: V }`), including non-string
+ * values such as `map<string, ValueOrigin>`. Not true for plain messages.
+ */
+type IsProtoMap<T> = T extends object ? string extends keyof T ? T extends readonly unknown[] ? false : true : false : false;
+/**
+ * Required proto3 maps/repeated/enums become optional for construction.
+ * protobuf-es enums are numeric, so required `number` fields soften too.
+ * Map *entry* keys (index signatures) are not softened — that would yield
+ * `Record<string, V | undefined>`.
+ */
+type SoftenField<V, K> = string extends K ? false : V extends readonly unknown[] ? true : IsProtoMap<V> extends true ? true : V extends number ? true : false;
+type OptionalKeys<T> = Exclude<{
+    [K in keyof T]-?: undefined extends T[K] ? K : never;
+}[keyof T], ProtoKey>;
+type RequiredKeys<T> = Exclude<keyof T, OptionalKeys<T> | ProtoKey>;
+type SoftenedKeys<T> = {
+    [K in RequiredKeys<T>]: SoftenField<T[K], K> extends true ? K : never;
+}[RequiredKeys<T>];
+type KeptRequiredKeys<T> = Exclude<RequiredKeys<T>, SoftenedKeys<T>>;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type StripProtoObject<T> = Simplify<{
+    [K in OptionalKeys<T> & keyof T]?: StripProto<Exclude<T[K], undefined>>;
+} & {
+    [K in SoftenedKeys<T>]?: StripProto<T[K]>;
+} & {
+    [K in KeptRequiredKeys<T>]: StripProto<T[K]>;
+}>;
+/**
+ * Recursively drop protobuf-es message internals for public SDK types:
+ *
+ * - removes `$typeName` / `$unknown` at every level (including nested messages)
+ * - keeps normal field optionality
+ * - softens required proto3 maps/repeated/enums to optional
+ * - keeps wire `Duration` opaque for provider helpers
+ * - maps `Timestamp` to `Date`
+ *
+ * Nested messages are stripped in place, so aliases do not need `Omit` + remap
+ * just to clean child protobuf fields.
+ */
+export type StripProto<T> = T extends Duration ? Duration : T extends Timestamp ? Date : T extends string | number | boolean | bigint | null | undefined | symbol | Date | Uint8Array | ((...args: never[]) => unknown) ? T : T extends readonly (infer U)[] ? StripProto<U>[] : T extends object ? StripProtoObject<T> : T;
+export {};

package/dist/internal/strip_proto.js

@@ -0,0 +1 @@
+export {};

package/dist/metadata/metadata_object.d.ts

@@ -0,0 +1,7 @@
+import type { MetadataObject } from "#contracts/sandbox_data_contracts.js";
+import type { MetadataPlain } from "#metadata/metadata_plain.js";
+export type { MetadataPlain } from "#metadata/metadata_plain.js";
+/** Converts a declarative map into the protobuf metadata object. */
+export declare function metadataObjectFromMap(source: Record<string, MetadataPlain> | undefined): MetadataObject | undefined;
+/** Converts a protobuf metadata object into a declarative map. */
+export declare function metadataObjectAsMap(source: MetadataObject | undefined): Record<string, MetadataPlain> | undefined;

package/dist/metadata/metadata_object.js

@@ -0,0 +1,103 @@
+// Handwritten helpers for protobuf metadata objects (mirrors Go sandbox metadata helpers).
+import { create } from "@bufbuild/protobuf";
+import { MetadataListSchema, MetadataObjectSchema, MetadataValueSchema, } from "@sandbox-kit/contracts/sandbox";
+/** Converts a declarative map into the protobuf metadata object. */
+export function metadataObjectFromMap(source) {
+    if (source === undefined)
+        return undefined;
+    const values = {};
+    for (const [key, value] of Object.entries(source)) {
+        values[key] = metadataValueFromPlain(value);
+    }
+    return create(MetadataObjectSchema, { values });
+}
+/** Converts a protobuf metadata object into a declarative map. */
+export function metadataObjectAsMap(source) {
+    if (source === undefined)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(source.values ?? {})) {
+        out[key] = metadataValueAsPlain(value);
+    }
+    return out;
+}
+function metadataValueFromPlain(value) {
+    // create() returns a protobuf Message; public aliases are StripProto shapes.
+    if (value === null)
+        return create(MetadataValueSchema, {});
+    if (typeof value === "boolean")
+        return create(MetadataValueSchema, {
+            value: { case: "boolean", value },
+        });
+    if (typeof value === "string")
+        return create(MetadataValueSchema, {
+            value: { case: "text", value },
+        });
+    if (typeof value === "bigint") {
+        if (value < 0n)
+            return create(MetadataValueSchema, {
+                value: { case: "signedInteger", value },
+            });
+        return create(MetadataValueSchema, {
+            value: { case: "unsignedInteger", value },
+        });
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("sandbox-kit: metadata numbers must be finite");
+        }
+        if (Number.isInteger(value)) {
+            const asBigInt = BigInt(value);
+            if (value < 0)
+                return create(MetadataValueSchema, {
+                    value: { case: "signedInteger", value: asBigInt },
+                });
+            return create(MetadataValueSchema, {
+                value: { case: "unsignedInteger", value: asBigInt },
+            });
+        }
+        return create(MetadataValueSchema, {
+            value: { case: "number", value },
+        });
+    }
+    if (value instanceof Uint8Array)
+        return create(MetadataValueSchema, {
+            value: { case: "binary", value },
+        });
+    if (Array.isArray(value)) {
+        return create(MetadataValueSchema, {
+            value: {
+                case: "list",
+                value: create(MetadataListSchema, {
+                    values: value.map(metadataValueFromPlain),
+                }),
+            },
+        });
+    }
+    return create(MetadataValueSchema, {
+        value: {
+            case: "object",
+            value: metadataObjectFromMap(value),
+        },
+    });
+}
+function metadataValueAsPlain(value) {
+    switch (value.value?.case) {
+        case undefined:
+            return null;
+        case "boolean":
+        case "text":
+        case "number":
+        case "binary":
+            return value.value.value;
+        case "signedInteger":
+        case "unsignedInteger":
+            return value.value.value;
+        case "list":
+            return (value.value.value?.values ?? []).map(metadataValueAsPlain);
+        case "object":
+            return metadataObjectAsMap(value.value.value) ?? {};
+        default:
+            return null;
+    }
+}

package/dist/metadata/metadata_plain.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Plain JSON-like values accepted for public metadata / providerOptions maps.
+ * Nested objects use an interface so IDEs do not expand the recursive union.
+ */
+export type MetadataPlain = null | boolean | string | number | bigint | Uint8Array | MetadataPlain[] | MetadataPlainObject;
+/** Nested object branch of {@link MetadataPlain}. */
+export interface MetadataPlainObject {
+    [key: string]: MetadataPlain;
+}

package/dist/metadata/metadata_plain.js

@@ -0,0 +1 @@
+export {};