@giselles-ai/sandkit 0.1.0

package/dist/types-BCgprbo8.d.ts

@@ -0,0 +1,47 @@
+interface PolicyServiceDescriptor {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly domains: readonly string[];
+    readonly headers?: readonly PolicyServiceHeaderTransform[];
+}
+interface PolicyServiceCredentialDefault {
+    readonly kind: "default";
+}
+interface PolicyServiceCredentialFromValue {
+    readonly kind: "value";
+    readonly value: string;
+}
+interface PolicyServiceCredentialRedacted {
+    readonly kind: "redacted";
+}
+type PolicyServiceCredentialSource = PolicyServiceCredentialDefault | PolicyServiceCredentialFromValue | PolicyServiceCredentialRedacted;
+interface PolicyServiceHeaderTransform {
+    readonly headerName: string;
+    readonly valuePrefix?: string;
+    readonly credential: PolicyServiceCredentialSource;
+}
+interface WorkspaceAllowAllPolicy {
+    readonly mode: "allow-all";
+}
+interface WorkspaceDenyAllPolicy {
+    readonly mode: "deny-all";
+}
+interface WorkspaceUserDefinedPolicy {
+    readonly mode: "allow-services";
+    readonly services: readonly PolicyServiceDescriptor[];
+}
+/**
+ * Durable workspace firewall policy.
+ *
+ * Sandkit models the same three policy shapes exposed by Vercel Sandbox firewall:
+ * - allow-all
+ * - deny-all
+ * - user-defined
+ *
+ * User-defined policies are currently expressed as allowed service descriptors.
+ * Reference: https://vercel.com/docs/vercel-sandbox/concepts/firewall
+ */
+type WorkspacePolicy = WorkspaceAllowAllPolicy | WorkspaceDenyAllPolicy | WorkspaceUserDefinedPolicy;
+
+export type { PolicyServiceDescriptor as P, WorkspacePolicy as W, PolicyServiceCredentialSource as a };

package/dist/types-BEKQnjeb.d.ts

@@ -0,0 +1,139 @@
+import { a as SandkitAdapter, S as SharedSetup, W as WorkspaceRecord, b as WorkspaceMetadata, c as WorkspaceStatus } from './types-Cy36bS1j.js';
+import { W as WorkspacePolicy } from './types-BCgprbo8.js';
+
+type JsonPrimitive = boolean | number | string | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+
+interface WorkspaceCreateOptions {
+    id?: string;
+    name?: string;
+    metadata?: WorkspaceMetadata;
+    policy?: WorkspacePolicy;
+    sandbox?: {
+        /**
+         * Durable workspace default for provider port publication. This affects
+         * create/restore behavior for live session/public URL flows, not the
+         * durable runCommand() unit-of-work model itself.
+         */
+        readonly exposedPorts?: readonly number[];
+    };
+    status?: WorkspaceStatus;
+    sandboxId?: string;
+    lastResumedAt?: string;
+}
+interface CommandResult {
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+}
+interface SandboxSessionLease {
+    readonly sandboxId: string;
+    readonly observedAt: string;
+    readonly expiresAt: string;
+}
+interface WorkspaceSandboxLease {
+    readonly sandboxId: string;
+    readonly observedAt: string;
+    readonly expiresAt: string;
+    readonly remainingMs: number;
+}
+interface WorkspaceSessionProcess {
+    readonly processId: string;
+    wait(): Promise<CommandResult>;
+    /**
+     * Accesses the same normalized log stream used by onStdout/onStderr callbacks.
+     * Sandkit keeps a single internal stream, so callbacks and logs() observe
+     * the same sequence and buffered historical chunks are replayed to new readers.
+     */
+    logs?: () => AsyncIterable<WorkspaceSessionLog>;
+}
+interface WorkspaceSessionLog {
+    readonly stream: "stdout" | "stderr";
+    readonly chunk: string;
+}
+interface WorkspaceSessionProcessStartInput {
+    readonly command: string;
+    readonly args: readonly string[];
+    /**
+     * Optional per-call policy override for this session process.
+     */
+    readonly policy?: WorkspacePolicy;
+    /**
+     * Callbacks consume chunks from Sandkit's normalized process log stream.
+     */
+    readonly onStdout?: ((chunk: string) => void) | undefined;
+    /**
+     * Callbacks consume chunks from Sandkit's normalized process log stream.
+     */
+    readonly onStderr?: ((chunk: string) => void) | undefined;
+}
+interface SandboxRunCommandOptions {
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly policy?: WorkspacePolicy;
+}
+interface PersistedSandboxState {
+    readonly kind: string;
+    readonly sessionId: string;
+    readonly state?: JsonValue;
+}
+interface SandboxDriver {
+    readonly id: string;
+    readonly provider: string;
+    applyPolicy(policy: WorkspacePolicy): Promise<void>;
+    /**
+     * Returns lease timing observed from the current sandbox instance.
+     * Some providers expose this as an interpreted timeout value.
+     * Sandkit persists lease updates only from explicit session open/extend paths,
+     * so callers should not treat mere reads as lease refreshes.
+     */
+    getSessionLease(): Promise<SandboxSessionLease>;
+    runCommand(command: string, args: string[]): Promise<CommandResult>;
+    startProcess?(input: WorkspaceSessionProcessStartInput): Promise<WorkspaceSessionProcess>;
+    /** Persists and restores durability state through commit() and attach/restore APIs. */
+    snapshot(): Promise<PersistedSandboxState>;
+    url?(port: number): Promise<string>;
+    extendTimeout?(durationMs: number): Promise<void>;
+}
+interface SandboxCreateOptions {
+    readonly policy: WorkspacePolicy;
+    readonly exposedPorts?: readonly number[];
+    readonly timeoutMs?: number;
+}
+interface SandboxDriverFactory {
+    createSandbox(workspace: WorkspaceRecord, options: SandboxCreateOptions): Promise<SandboxDriver>;
+    resumeSandbox(workspace: WorkspaceRecord, snapshot: PersistedSandboxState, options: SandboxCreateOptions): Promise<SandboxDriver>;
+    isSessionUnavailableError?(error: unknown): boolean;
+}
+interface VercelSandboxOptions {
+    runtime?: string;
+    /**
+     * Provider default sandbox lease timeout in milliseconds. Sandkit uses this
+     * when creating or restoring a sandbox unless openSession({ timeoutMs })
+     * supplies a live-session override.
+     */
+    defaultTimeout?: number;
+    /**
+     * Legacy alias retained for compatibility with existing call sites.
+     * Prefer defaultTimeout for new code.
+     */
+    timeout?: number;
+}
+declare const sandboxProviderContract: unique symbol;
+type SandboxProviderRecord = {
+    readonly provider: string;
+    readonly driverFactory: SandboxDriverFactory;
+};
+interface SandkitSandboxProvider {
+    readonly [sandboxProviderContract]: SandboxProviderRecord;
+}
+interface SandkitOptions {
+    readonly database?: SandkitAdapter | undefined;
+    readonly setup?: SharedSetup | undefined;
+    readonly network?: readonly unknown[] | undefined;
+    readonly sandbox: SandkitSandboxProvider;
+}
+
+export type { CommandResult as C, PersistedSandboxState as P, SandkitOptions as S, VercelSandboxOptions as V, WorkspaceSessionProcess as W, SandboxDriverFactory as a, SandboxRunCommandOptions as b, WorkspaceSessionProcessStartInput as c, WorkspaceSandboxLease as d, WorkspaceCreateOptions as e, SandboxCreateOptions as f, SandboxDriver as g, SandkitSandboxProvider as h };

package/dist/types-Cy36bS1j.d.ts

@@ -0,0 +1,138 @@
+import { W as WorkspacePolicy } from './types-BCgprbo8.js';
+
+type WorkspaceStatus = "active" | "inactive" | "archived";
+type RunStatus = "started" | "succeeded" | "failed";
+interface WorkspaceMetadata {
+    [key: string]: unknown;
+}
+type SharedSetupStateValue = null | boolean | number | string | SharedSetupStateValue[] | {
+    [key: string]: SharedSetupStateValue;
+};
+interface SharedSetup {
+    readonly command: string;
+    readonly args?: readonly string[];
+    /**
+     * Shared setup state is durable and reused across workspaces, so this policy
+     * must also be durable. Explicit secret-bearing policies are rejected.
+     */
+    readonly policy?: WorkspacePolicy;
+}
+/**
+ * Internal durable artifact produced by a successful shared bootstrap.
+ */
+interface SharedSetupState {
+    readonly kind: string;
+    readonly sessionId: string;
+    readonly state?: SharedSetupStateValue;
+}
+interface WorkspaceRecord {
+    id: string;
+    name?: string;
+    metadata?: WorkspaceMetadata;
+    status: WorkspaceStatus;
+    sandboxId?: string;
+    lastResumedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface WorkspaceCreateInput {
+    id?: string;
+    name?: string;
+    metadata?: WorkspaceMetadata;
+    policy?: WorkspacePolicy;
+    status?: WorkspaceStatus;
+    sandboxId?: string;
+    lastResumedAt?: string;
+}
+interface WorkspaceUpdateInput {
+    name?: string;
+    metadata?: WorkspaceMetadata;
+    status?: WorkspaceStatus;
+    sandboxId?: string | null;
+    lastResumedAt?: string | null;
+}
+interface SetupStateRecord {
+    readonly id: string;
+    readonly state: SharedSetupState;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+interface SetupStatePutInput {
+    readonly id: string;
+    readonly state: SharedSetupState;
+}
+interface SetupStateAdapter {
+    getSetupState(id: string): Promise<SetupStateRecord | null>;
+    putSetupState(input: SetupStatePutInput): Promise<SetupStateRecord>;
+    deleteSetupState(id: string): Promise<void>;
+}
+interface WorkspaceAdapter {
+    createWorkspace(input?: WorkspaceCreateInput): Promise<WorkspaceRecord>;
+    getWorkspace(id: string): Promise<WorkspaceRecord | null>;
+    updateWorkspace(id: string, input: WorkspaceUpdateInput): Promise<WorkspaceRecord>;
+}
+interface RunRecord {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly provider: string;
+    readonly executionTargetId: string;
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly status: RunStatus;
+    readonly exitCode?: number;
+    readonly stdout?: string;
+    readonly stderr?: string;
+    readonly startedAt: string;
+    readonly finishedAt?: string;
+    readonly policySnapshotId?: string;
+    readonly providerCommit?: unknown;
+}
+interface RunCreateInput {
+    id?: string;
+    workspaceId: string;
+    provider: string;
+    executionTargetId: string;
+    command: string;
+    args?: readonly string[] | null;
+    status?: RunStatus;
+    startedAt?: string;
+    policySnapshotId?: string | null;
+}
+interface RunFinishInput {
+    status: RunStatus;
+    finishedAt: string;
+    exitCode?: number | null;
+    stdout?: string | null;
+    stderr?: string | null;
+    providerCommit?: unknown;
+}
+interface PolicySnapshotRecord {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly policyId: string;
+    readonly config: unknown;
+    readonly createdAt: string;
+}
+interface PolicySnapshotCreateInput {
+    id?: string;
+    workspaceId: string;
+    policyId: string;
+    config: unknown;
+    createdAt?: string;
+}
+interface RunAdapter {
+    createRun(input: RunCreateInput): Promise<RunRecord>;
+    finishRun(id: string, input: RunFinishInput): Promise<RunRecord>;
+}
+interface PolicySnapshotAdapter {
+    createPolicySnapshot(input: PolicySnapshotCreateInput): Promise<PolicySnapshotRecord>;
+}
+interface SandkitAdapter {
+    readonly id: string;
+    readonly workspaces: WorkspaceAdapter;
+    readonly setupStates: SetupStateAdapter;
+    readonly runs: RunAdapter;
+    readonly policySnapshots: PolicySnapshotAdapter;
+}
+
+export type { SharedSetup as S, WorkspaceRecord as W, SandkitAdapter as a, WorkspaceMetadata as b, WorkspaceStatus as c };

package/package.json

@@ -0,0 +1,126 @@
+{
+  "name": "@giselles-ai/sandkit",
+  "version": "0.1.0",
+  "description": "Workspace state, session management, and durable command execution for Vercel Sandbox.",
+  "keywords": [
+    "agent",
+    "drizzle",
+    "durable-execution",
+    "resumable-workflows",
+    "sandbox",
+    "sandbox-orchestration",
+    "session-management",
+    "state-management",
+    "stateful-sandbox",
+    "typescript",
+    "vercel",
+    "vercel-sandbox",
+    "workflow",
+    "workspace"
+  ],
+  "homepage": "https://github.com/giselles-ai/sandkit",
+  "bugs": {
+    "url": "https://github.com/giselles-ai/sandkit/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/giselles-ai/sandkit.git"
+  },
+  "bin": {
+    "sandkit": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./adapters/drizzle": {
+      "types": "./dist/adapters/drizzle.d.ts",
+      "import": "./dist/adapters/drizzle.js",
+      "default": "./dist/adapters/drizzle.js"
+    },
+    "./adapters/memory": {
+      "types": "./dist/adapters/memory.d.ts",
+      "import": "./dist/adapters/memory.js",
+      "default": "./dist/adapters/memory.js"
+    },
+    "./adapters/sqlite-bun": {
+      "types": "./dist/adapters/sqlite-bun.d.ts",
+      "import": "./dist/adapters/sqlite-bun.js",
+      "default": "./dist/adapters/sqlite-bun.js"
+    },
+    "./policies/ai-gateway": {
+      "types": "./dist/policies/ai-gateway.d.ts",
+      "import": "./dist/policies/ai-gateway.js",
+      "default": "./dist/policies/ai-gateway.js"
+    },
+    "./policies/codex": {
+      "types": "./dist/policies/codex.d.ts",
+      "import": "./dist/policies/codex.js",
+      "default": "./dist/policies/codex.js"
+    },
+    "./policies/gemini": {
+      "types": "./dist/policies/gemini.d.ts",
+      "import": "./dist/policies/gemini.js",
+      "default": "./dist/policies/gemini.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.js",
+      "default": "./dist/schema/index.js"
+    },
+    "./integrations/vercel": {
+      "types": "./dist/integrations/vercel.d.ts",
+      "import": "./dist/integrations/vercel.js",
+      "default": "./dist/integrations/vercel.js"
+    },
+    "./integrations/mock": {
+      "types": "./dist/integrations/mock.d.ts",
+      "import": "./dist/integrations/mock.js",
+      "default": "./dist/integrations/mock.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js",
+      "default": "./dist/cli/index.js"
+    }
+  },
+  "scripts": {
+    "lint": "oxlint src tsup.config.ts",
+    "lint:fix": "oxlint src tsup.config.ts --fix",
+    "fmt": "oxfmt src tsup.config.ts",
+    "fmt:check": "oxfmt --check src tsup.config.ts",
+    "build": "bun run clean && tsup",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "@vercel/sandbox": "1.8.1"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "del-cli": "7.0.0",
+    "drizzle-orm": "0.45.1",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.44.2"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    }
+  }
+}