@giselles-ai/sandkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Giselle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# Sandkit
+
+Sandkit makes Vercel Sandbox stateful.
+
+Sandkit adds workspace state, session management, durable command execution, and resumable sandbox workflows to Vercel Sandbox.
+
+It keeps two paths explicit:
+
+- `workspace.sandbox.runCommand(...)` for durable, one-command-at-a-time work
+- `openSession()` / `attachSession()` for a live leased sandbox when you need an interactive process
+
+An active session is an exclusive workspace lease. While a live session is open, `runCommand()` is unavailable until you attach to that session or commit it.
+
+Provider-specific behavior still matters, but the public API stays centered on workspaces, policies, and durable state.
+
+## Problem
+
+Vercel Sandbox is ephemeral by design. It does not give you durable workspaces, session lifecycle, or a clear boundary between one-shot commands and live attached execution.
+
+- No built-in workspace identity or durable workspace state
+- No session management abstraction for live attach / resume
+- No durable command boundary for one-command-at-a-time work
+- Teams end up rebuilding the same sandbox state and lifecycle layer around jobs, agents, and recovery flows
+
+## Solution
+
+Sandkit adds a workspace state layer on top of Vercel Sandbox:
+
+- Persistent workspaces for sandbox state management
+- Live session lifecycle with explicit attach / commit semantics
+- Durable command execution through `runCommand(...)` for committed work
+- Policy controls that stay part of workspace state
+- Resumable sandbox workflows for long-running apps and control planes
+
+## Positioning
+
+| Tool                                  | Responsibility                                                                                                           |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Vercel Sandbox                        | Ephemeral execution environment                                                                                          |
+| Sandkit                               | State and lifecycle layer for sandboxed execution: workspaces, session lifecycle, durable command boundaries, and resume |
+| Workflow engines / app control planes | Decide when and why work runs                                                                                            |
+
+## Primary Use Case: Persistent Workspaces for AI Coding Agents
+
+Sandkit is especially useful when an agent or long-running sandbox app needs to keep a workspace alive across runs, attach to a live process, expose a public URL, and commit progress durably.
+
+## Install
+
+```sh
+npm install @giselles-ai/sandkit
+```
+
+With Drizzle:
+
+```sh
+npm install @giselles-ai/sandkit drizzle-orm
+```
+
+## Quick Start
+
+> Migration note: `sandkit(...)` was renamed to `createSandkit(...)` and this package is not yet aliased.
+> Callers must update imports and call sites from `sandkit` to `createSandkit`.
+
+```ts
+import { Database } from "bun:sqlite";
+
+import { createSandkit } from "@giselles-ai/sandkit";
+import { createBunSqliteAdapter } from "@giselles-ai/sandkit/adapters/sqlite-bun";
+import { vercelSandbox } from "@giselles-ai/sandkit/integrations/vercel";
+
+const database = new Database("./sandkit.sqlite");
+const workspaceAdapter = createBunSqliteAdapter(database);
+
+const sandkit = createSandkit({
+  database: workspaceAdapter,
+  sandbox: vercelSandbox({
+    defaultTimeout: 60_000,
+  }),
+});
+
+const workspace = await sandkit.createWorkspace({
+  name: "hello-sandkit",
+});
+
+await workspace.sandbox.runCommand({
+  command: "sh",
+  args: ["-lc", "echo 'hello world' > ./hello.txt"],
+});
+
+const result = await workspace.sandbox.runCommand({
+  command: "cat",
+  args: ["./hello.txt"],
+});
+
+console.log(result.stdout.trim());
+```
+
+Set `VERCEL_OIDC_TOKEN` for local runs or `VERCEL_ACCESS_TOKEN` in CI before creating a Vercel-backed sandbox.
+
+Declare `exposedPorts` on `createWorkspace({ sandbox: ... })` only when you need a live session URL. `defaultTimeout` is the provider-level lease default; override a specific live session with `openSession({ timeoutMs })`.
+
+## Setup bootstrap
+
+Pass setup to `createSandkit({ setup })` to seed a shared durable state used by all workspaces on the same adapter.
+Each workspace starts from that shared bootstrap snapshot when no workspace-specific durable state exists.
+Sandkit persists one shared bootstrap state per adapter and bootstrap definition (command + args + explicit setup policy), runs setup once per unique bootstrap definition, and reuses the matching state for subsequent workspaces.
+If a shared bootstrap state is stale or unusable, Sandkit re-runs setup and persists a replacement.
+By default setup runs under the workspace policy; set `setup.policy` when bootstrap needs broader access than steady-state execution.
+Because setup becomes shared durable state, `setup.policy` must also be durable: explicit secret-bearing policies are rejected there.
+
+`setup` durability is adapter-backed. With a persistent adapter such as Bun SQLite or Drizzle, the shared bootstrap survives process restarts. With the default in-memory adapter, it does not.
+
+```ts
+import { createSandkit, allowAll } from "@giselles-ai/sandkit";
+import { vercelSandbox } from "@giselles-ai/sandkit/integrations/vercel";
+
+const sandkit = createSandkit({
+  sandbox: vercelSandbox(),
+  setup: {
+    command: "sh",
+    args: ["-lc", "npm ci"],
+    policy: allowAll(),
+  },
+});
+
+const workspace = await sandkit.createWorkspace({
+  name: "bootstrapped-workspace",
+});
+```
+
+## Configuration
+
+Provide a `sandbox` provider explicitly (for example `vercelSandbox(...)`).
+If you do not pass `database`, Sandkit defaults to the in-memory adapter. That default is useful for local tests and internal development, but the primary published usage is an explicit Vercel provider plus a persistent adapter.
+
+## Policies
+
+- `codex()` reads `CODEX_API_KEY`
+- `gemini()` reads `GEMINI_API_KEY`
+- `github()` reads `GITHUB_TOKEN`
+- `aiGateway()` reads `AI_GATEWAY_API_KEY` from host env and allows the hostname (plus wildcard) from `AI_GATEWAY_BASE_URL`.
+  `AI_GATEWAY_BASE_URL` ports are ignored for allow-listing; only host/domain matches are used.
+
+Durable default policy belongs to the workspace: use `createWorkspace({ policy: ... })` when you create it, or `workspace.setPolicy(...)` later. Pass `policy` to `runCommand(...)` for one-off overrides.
+
+## Schema Generation
+
+```sh
+npx @giselles-ai/sandkit generate --adapter drizzle --provider sqlite
+```
+
+If the project already has a Drizzle setup, provider discovery can infer the dialect:
+
+```sh
+npx @giselles-ai/sandkit generate
+```
+
+## Examples
+
+- `examples/sandbox-openclaw`
+- `smoke/drizzle-sample`
+
+Repository: [github.com/giselles-ai/sandkit](https://github.com/giselles-ai/sandkit)

package/dist/adapters/drizzle.d.ts

@@ -0,0 +1,83 @@
+import { SQLWrapper } from 'drizzle-orm';
+import { a as SandkitAdapter } from '../types-Cy36bS1j.js';
+import '../types-BCgprbo8.js';
+
+interface DrizzleWorkspaceTableShape {
+    readonly id: SQLWrapper;
+    readonly name: unknown;
+    readonly metadata: unknown;
+    readonly status: unknown;
+    readonly sandboxId: unknown;
+    readonly lastResumedAt: unknown;
+    readonly createdAt: unknown;
+    readonly updatedAt: unknown;
+}
+interface DrizzleRunTableShape {
+    readonly id: SQLWrapper;
+    readonly workspace_id: unknown;
+    readonly provider: unknown;
+    readonly execution_target_id: unknown;
+    readonly command: unknown;
+    readonly args: unknown;
+    readonly status: unknown;
+    readonly policy_snapshot_id: unknown;
+    readonly provider_commit: unknown;
+    readonly exit_code: unknown;
+    readonly stdout: unknown;
+    readonly stderr: unknown;
+    readonly started_at: unknown;
+    readonly finished_at: unknown;
+}
+interface DrizzlePolicySnapshotTableShape {
+    readonly id: SQLWrapper;
+    readonly workspace_id: unknown;
+    readonly policy_id: unknown;
+    readonly config: unknown;
+    readonly created_at: unknown;
+}
+interface DrizzleSetupStateTableShape {
+    readonly id: SQLWrapper;
+    readonly state: unknown;
+    readonly createdAt: unknown;
+    readonly updatedAt: unknown;
+}
+interface DrizzleSchemaMap {
+    [key: string]: unknown;
+}
+interface DrizzleMetadata {
+    readonly fullSchema?: DrizzleSchemaMap;
+}
+interface DrizzleDatabaseLike {
+    select(): {
+        from(table: object): {
+            where(condition: unknown): {
+                limit(limit: number): Promise<unknown[]>;
+            };
+        };
+    };
+    insert(table: object): {
+        values(value: Record<string, unknown>): Promise<unknown>;
+    };
+    update(table: object): {
+        set(value: Record<string, unknown>): {
+            where(condition: unknown): Promise<unknown>;
+        };
+    };
+    delete(table: object): {
+        where(condition: unknown): Promise<unknown>;
+    };
+    readonly _?: DrizzleMetadata;
+}
+interface DrizzleAdapterOptions<TWorkspaces extends DrizzleWorkspaceTableShape, TRuns extends DrizzleRunTableShape, TPolicySnapshots extends DrizzlePolicySnapshotTableShape, TSetupStates extends DrizzleSetupStateTableShape = DrizzleSetupStateTableShape> {
+    provider: "sqlite" | "postgresql" | "mysql";
+    workspaces?: TWorkspaces;
+    runs?: TRuns;
+    policySnapshots?: TPolicySnapshots;
+    setupStates?: TSetupStates;
+    id?: string;
+}
+declare function drizzleAdapter<TWorkspaces extends DrizzleWorkspaceTableShape, TRuns extends DrizzleRunTableShape, TPolicySnapshots extends DrizzlePolicySnapshotTableShape, TSetupStates extends DrizzleSetupStateTableShape = DrizzleSetupStateTableShape>(db: DrizzleDatabaseLike, options: DrizzleAdapterOptions<TWorkspaces, TRuns, TPolicySnapshots, TSetupStates>): SandkitAdapter;
+type DrizzleWorkspaceTable = DrizzleWorkspaceTableShape;
+type DrizzleRunTable = DrizzleRunTableShape;
+
+export { type DrizzleAdapterOptions, type DrizzleRunTable, type DrizzleWorkspaceTable, drizzleAdapter };

package/dist/adapters/drizzle.js

@@ -0,0 +1,9 @@
+import {
+  drizzleAdapter
+} from "../chunk-BDPTYR6V.js";
+import "../chunk-RMMOQD5Y.js";
+import "../chunk-DLGUA3H7.js";
+export {
+  drizzleAdapter
+};
+//# sourceMappingURL=drizzle.js.map

package/dist/adapters/drizzle.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/adapters/memory.d.ts

@@ -0,0 +1,6 @@
+import { a as SandkitAdapter } from '../types-Cy36bS1j.js';
+import '../types-BCgprbo8.js';
+
+declare const createMemoryAdapter: () => SandkitAdapter;
+
+export { createMemoryAdapter };

package/dist/adapters/memory.js

@@ -0,0 +1,8 @@
+import {
+  createMemoryAdapter
+} from "../chunk-CSOBTLWV.js";
+import "../chunk-DLGUA3H7.js";
+export {
+  createMemoryAdapter
+};
+//# sourceMappingURL=memory.js.map

package/dist/adapters/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/adapters/sqlite-bun.d.ts

@@ -0,0 +1,7 @@
+import { Database } from 'bun:sqlite';
+import { a as SandkitAdapter } from '../types-Cy36bS1j.js';
+import '../types-BCgprbo8.js';
+
+declare function createBunSqliteAdapter(db: Database): SandkitAdapter;
+
+export { createBunSqliteAdapter };

package/dist/adapters/sqlite-bun.js

@@ -0,0 +1,8 @@
+import {
+  createBunSqliteAdapter
+} from "../chunk-UDFWES6J.js";
+import "../chunk-DLGUA3H7.js";
+export {
+  createBunSqliteAdapter
+};
+//# sourceMappingURL=sqlite-bun.js.map

package/dist/adapters/sqlite-bun.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}