@giselles-ai/sandkit 0.1.1 → 0.1.2

package/README.md

@@ -11,6 +11,8 @@ It keeps two paths explicit:
 
 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.
 
+Durable lock enforcement is currently in-process (`packages/sandkit` only). Concurrent durable commands for the same workspace are excluded while one is in flight in the same process.
+
 Provider-specific behavior still matters, but the public API stays centered on workspaces, policies, and durable state.
 
 ## Problem
@@ -95,18 +97,43 @@ const result = await workspace.sandbox.runCommand({
 console.log(result.stdout.trim());
 ```
 
+`runCommand(...)` (without `detached`) resolves to `CommandResult` only after the full unit-of-work is complete: process exit, snapshot/commit, and persist.
+
+For detached execution, pass `detached: true` and you get a `Command` object. Observe logs and then await durable completion:
+
+```ts
+const command = await workspace.sandbox.runCommand({
+  command: "sh",
+  args: ["-lc", "echo 'start'; sleep 1; echo 'done'"],
+  detached: true,
+});
+for await (const chunk of command.logs?.() ?? []) {
+  console.log(`${chunk.stream}: ${chunk.chunk}`);
+}
+
+const commandResult = await command.wait();
+```
+
 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` is the shared bootstrap definition, not the materialized artifact.
+It is optional.
+When `setup` is provided, it is the shared bootstrap command, args, and required durable `policy`.
+This produces adapter-scoped shared bootstrap state keyed by `adapter.id` + setup definition fingerprint.
+Multiple Sandkit instances using the same adapter and setup definition can reuse the same shared bootstrap state.
+
+`sandkit.bootstrap()` is an optional eager materialization step:
+
+- it creates shared bootstrap state if missing,
+- it leaves existing shared bootstrap state untouched,
+- it does not run a restore path to prove an existing shared bootstrap state is still usable.
+
+Without `bootstrap()`, shared setup is still materialized lazily on first workspace use (first `runCommand(...)` or `openSession(...)` that needs it).
+Stale or unusable shared bootstrap artifacts are detected and rebuilt in those workspace flows, not by `bootstrap()` alone.
 
 `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.
 
@@ -123,6 +150,9 @@ const sandkit = createSandkit({
   },
 });
 
+await sandkit.bootstrap();
+
+// Optional: omit bootstrap() and let setup materialize on first workspace use.
 const workspace = await sandkit.createWorkspace({
   name: "bootstrapped-workspace",
 });
@@ -135,6 +165,8 @@ If you do not pass `database`, Sandkit defaults to the in-memory adapter. That d
 
 ## Policies
 
+- `npm()` allows the public npm registry host `registry.npmjs.org`
+- `bun()` allows Bun install/distribution hosts `bun.sh` and `bun.com`
 - `codex()` reads `CODEX_API_KEY`
 - `gemini()` reads `GEMINI_API_KEY`
 - `github()` reads `GITHUB_TOKEN` and maps it through Vercel Sandbox firewall transforms:
@@ -144,6 +176,14 @@ If you do not pass `database`, Sandkit defaults to the in-memory adapter. That d
 - `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.
 
+For JavaScript package bootstrap, prefer explicit service presets over `allowAll()`:
+
+```ts
+import { allowServices, bun, npm } from "@giselles-ai/sandkit";
+
+const policy = allowServices([bun(), npm()]);
+```
+
 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

package/dist/adapters/drizzle.d.ts

@@ -1,5 +1,5 @@
 import { SQLWrapper } from 'drizzle-orm';
-import { a as SandkitAdapter } from '../types-BRMAvcWc.js';
+import { a as SandkitAdapter } from '../types-DNpj280o.js';
 import '../types-Dpr_BkF9.js';
 
 interface DrizzleWorkspaceTableShape {

package/dist/adapters/memory.d.ts

@@ -1,4 +1,4 @@
-import { a as SandkitAdapter } from '../types-BRMAvcWc.js';
+import { a as SandkitAdapter } from '../types-DNpj280o.js';
 import '../types-Dpr_BkF9.js';
 
 declare const createMemoryAdapter: () => SandkitAdapter;

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

@@ -1,5 +1,5 @@
 import { Database } from 'bun:sqlite';
-import { a as SandkitAdapter } from '../types-BRMAvcWc.js';
+import { a as SandkitAdapter } from '../types-DNpj280o.js';
 import '../types-Dpr_BkF9.js';
 
 declare function createBunSqliteAdapter(db: Database): SandkitAdapter;

package/dist/chunk-T76VM5D2.js

@@ -0,0 +1,23 @@
+import {
+  allowService
+} from "./chunk-NKTNTBOY.js";
+
+// src/policies/npm.ts
+var NPM_DOMAINS = ["registry.npmjs.org"];
+function npm() {
+  return {
+    id: "npm",
+    name: "npm",
+    description: "Allow outbound access to the public npm package registry.",
+    domains: NPM_DOMAINS
+  };
+}
+function allowNpm() {
+  return allowService(npm());
+}
+
+export {
+  npm,
+  allowNpm
+};
+//# sourceMappingURL=chunk-T76VM5D2.js.map

package/dist/chunk-T76VM5D2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/policies/npm.ts"],"sourcesContent":["import { allowService } from \"./dsl.ts\";\nimport type { PolicyServiceDescriptor, WorkspacePolicy } from \"./types.ts\";\n\nconst NPM_DOMAINS = [\"registry.npmjs.org\"] as const;\n\n/**\n * Allow outbound access to the public npm package registry.\n *\n * Keep this preset scoped to the actual package source host instead of\n * broadening to unrelated npm web properties.\n */\nexport function npm(): PolicyServiceDescriptor {\n  return {\n    id: \"npm\",\n    name: \"npm\",\n    description: \"Allow outbound access to the public npm package registry.\",\n    domains: NPM_DOMAINS,\n  };\n}\n\nexport function allowNpm(): WorkspacePolicy {\n  return allowService(npm());\n}\n"],"mappings":";;;;;AAGA,IAAM,cAAc,CAAC,oBAAoB;AAQlC,SAAS,MAA+B;AAC7C,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,MAAM;AAAA,IACN,aAAa;AAAA,IACb,SAAS;AAAA,EACX;AACF;AAEO,SAAS,WAA4B;AAC1C,SAAO,aAAa,IAAI,CAAC;AAC3B;","names":[]}

package/dist/{chunk-HVYCAAZQ.js → chunk-XN6DGLRP.js}

@@ -22,4 +22,4 @@ export {
   createSandboxProvider,
   getSandboxDriverFactory
 };
-//# sourceMappingURL=chunk-HVYCAAZQ.js.map
+//# sourceMappingURL=chunk-XN6DGLRP.js.map

package/dist/chunk-XN6DGLRP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { SandkitAdapter, WorkspaceRecord } from \"./adapters/types.ts\";\nimport type {\n  PolicySnapshotAdapter,\n  PolicySnapshotRecord,\n  PolicySnapshotCreateInput,\n  RunAdapter,\n  RunCreateInput,\n  RunFinishInput,\n  RunRecord,\n  RunStatus,\n  SetupStateAdapter,\n  SetupStateRecord,\n  SetupStatePutInput,\n  WorkspaceMetadata,\n  SharedSetup,\n  SharedSetupState,\n  WorkspaceStatus,\n} from \"./adapters/types.ts\";\nimport type { WorkspacePolicy } from \"./policies/types.ts\";\n\nexport type JsonPrimitive = boolean | number | string | null;\n\nexport type JsonValue =\n  | JsonPrimitive\n  | JsonValue[]\n  | {\n      [key: string]: JsonValue;\n    };\n\nexport type {\n  SandkitAdapter,\n  WorkspaceRecord,\n  RunAdapter,\n  RunCreateInput,\n  RunFinishInput,\n  RunRecord,\n  PolicySnapshotAdapter,\n  PolicySnapshotRecord,\n  PolicySnapshotCreateInput,\n  RunStatus,\n  SetupStateAdapter,\n  SetupStateRecord,\n  SetupStatePutInput,\n  SharedSetup,\n  SharedSetupState,\n};\nexport type { WorkspacePolicy };\n\nexport interface WorkspaceCreateOptions {\n  id?: string;\n  name?: string;\n  metadata?: WorkspaceMetadata;\n  policy?: WorkspacePolicy;\n  sandbox?: {\n    /**\n     * Durable workspace default for provider port publication. This affects\n     * create/restore behavior for live session/public URL flows, not the\n     * durable runCommand() unit-of-work model itself.\n     */\n    readonly exposedPorts?: readonly number[];\n  };\n  status?: WorkspaceStatus;\n  sandboxId?: string;\n  lastResumedAt?: string;\n}\n\nexport interface CommandResult {\n  exitCode: number;\n  stderr: string;\n  stdout: string;\n}\n\nexport interface Command {\n  /**\n   * Wait for durable completion of the command unit-of-work: process exit,\n   * snapshot/commit, and persist outcome.\n   */\n  readonly wait: () => Promise<CommandResult>;\n  /**\n   * Ephemeral log stream for detached execution. The stream is live-only and does\n   * not participate in durable state replay.\n   */\n  readonly logs?: () => AsyncIterable<WorkspaceSessionLog>;\n}\n\nexport interface SandboxSessionLease {\n  readonly sandboxId: string;\n  readonly observedAt: string;\n  readonly expiresAt: string;\n}\n\nexport interface WorkspaceSandboxLease {\n  readonly sandboxId: string;\n  readonly observedAt: string;\n  readonly expiresAt: string;\n  readonly remainingMs: number;\n}\n\nexport interface WorkspaceSessionProcess {\n  readonly processId: string;\n  wait(): Promise<CommandResult>;\n  /**\n   * Accesses the same normalized log stream used by onStdout/onStderr callbacks.\n   * Sandkit keeps a single internal stream, so callbacks and logs() observe\n   * the same sequence and buffered historical chunks are replayed to new readers.\n   */\n  logs?: () => AsyncIterable<WorkspaceSessionLog>;\n}\n\nexport interface WorkspaceSessionLog {\n  readonly stream: \"stdout\" | \"stderr\";\n  readonly chunk: string;\n}\n\nexport interface WorkspaceSessionProcessStartInput {\n  readonly command: string;\n  readonly args: readonly string[];\n  /**\n   * Optional per-call policy override for this session process.\n   */\n  readonly policy?: WorkspacePolicy;\n  /**\n   * Callbacks consume chunks from Sandkit's normalized process log stream.\n   */\n  readonly onStdout?: ((chunk: string) => void) | undefined;\n  /**\n   * Callbacks consume chunks from Sandkit's normalized process log stream.\n   */\n  readonly onStderr?: ((chunk: string) => void) | undefined;\n}\n\nexport interface WorkspaceSessionRunCommandOptions {\n  readonly command: string;\n  readonly args?: readonly string[];\n  readonly policy?: WorkspacePolicy;\n}\n\ninterface WorkspaceRunCommandBaseOptions {\n  readonly command: string;\n  readonly args?: readonly string[];\n  readonly policy?: WorkspacePolicy;\n  /**\n   * Ephemeral timeout override for this durable runCommand() invocation.\n   * This affects sandbox create/restore lease timing for the run only and\n   * must not mutate durable workspace defaults.\n   */\n  readonly timeoutMs?: number;\n}\n\nexport interface WorkspaceRunCommandOptions extends WorkspaceRunCommandBaseOptions {}\n\nexport interface WorkspaceRunCommandDetachedOptions extends WorkspaceRunCommandBaseOptions {\n  readonly detached: true;\n}\n\nexport type SandboxRunCommandOptions =\n  | WorkspaceRunCommandOptions\n  | WorkspaceRunCommandDetachedOptions;\n\nexport interface PersistedSandboxState {\n  readonly kind: string;\n  readonly sessionId: string;\n  readonly state?: JsonValue;\n}\n\nexport interface SandboxDriver {\n  readonly id: string;\n  readonly provider: string;\n  applyPolicy(policy: WorkspacePolicy): Promise<void>;\n  /**\n   * Returns lease timing observed from the current sandbox instance.\n   * Some providers expose this as an interpreted timeout value.\n   * Sandkit persists lease updates only from explicit session open/extend paths,\n   * so callers should not treat mere reads as lease refreshes.\n   */\n  getSessionLease(): Promise<SandboxSessionLease>;\n  runCommand(\n    command: string,\n    args: string[],\n    options?: { readonly detached?: boolean },\n  ): Promise<Command>;\n  startProcess?(input: WorkspaceSessionProcessStartInput): Promise<WorkspaceSessionProcess>;\n  /** Persists and restores durability state through commit() and attach/restore APIs. */\n  snapshot(): Promise<PersistedSandboxState>;\n  url?(port: number): Promise<string>;\n  extendTimeout?(durationMs: number): Promise<void>;\n}\n\nexport interface SandboxCreateOptions {\n  readonly policy: WorkspacePolicy;\n  readonly exposedPorts?: readonly number[];\n  readonly timeoutMs?: number;\n}\n\nexport interface SandboxDriverFactory {\n  createSandbox(workspace: WorkspaceRecord, options: SandboxCreateOptions): Promise<SandboxDriver>;\n  resumeSandbox(\n    workspace: WorkspaceRecord,\n    snapshot: PersistedSandboxState,\n    options: SandboxCreateOptions,\n  ): Promise<SandboxDriver>;\n  isSessionUnavailableError?(error: unknown): boolean;\n}\n\nexport interface VercelSandboxOptions {\n  runtime?: string;\n  /**\n   * Provider default sandbox lease timeout in milliseconds. Sandkit uses this\n   * when creating or restoring a sandbox unless openSession({ timeoutMs })\n   * supplies a live-session override.\n   */\n  defaultTimeout?: number;\n  /**\n   * Legacy alias retained for compatibility with existing call sites.\n   * Prefer defaultTimeout for new code.\n   */\n  timeout?: number;\n}\n\nconst sandboxProviderContract = Symbol(\"sandkit.sandbox.provider\");\n\ntype SandboxProviderRecord = {\n  readonly provider: string;\n  readonly driverFactory: SandboxDriverFactory;\n};\n\nexport interface SandkitSandboxProvider {\n  readonly [sandboxProviderContract]: SandboxProviderRecord;\n}\n\nexport function createSandboxProvider(\n  provider: string,\n  driverFactory: SandboxDriverFactory,\n): SandkitSandboxProvider {\n  return {\n    [sandboxProviderContract]: {\n      provider,\n      driverFactory,\n    },\n  };\n}\n\nexport function getSandboxDriverFactory(\n  sandboxProvider: SandkitSandboxProvider,\n): SandboxDriverFactory {\n  const driverFactory = sandboxProvider[sandboxProviderContract]?.driverFactory;\n  if (!driverFactory) {\n    throw new Error(\n      \"SandkitOptions.sandbox is invalid. Pass a provider created by Sandkit integrations such as vercelSandbox(...).\",\n    );\n  }\n\n  return driverFactory;\n}\n\nexport interface SandkitOptions {\n  readonly database?: SandkitAdapter | undefined;\n  readonly setup?: SharedSetup | undefined;\n  readonly network?: readonly unknown[] | undefined;\n  readonly sandbox: SandkitSandboxProvider;\n}\n"],"mappings":";AA2NA,IAAM,0BAA0B,uBAAO,0BAA0B;AAW1D,SAAS,sBACd,UACA,eACwB;AACxB,SAAO;AAAA,IACL,CAAC,uBAAuB,GAAG;AAAA,MACzB;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;AAEO,SAAS,wBACd,iBACsB;AACtB,QAAM,gBAAgB,gBAAgB,uBAAuB,GAAG;AAChE,MAAI,CAAC,eAAe;AAClB,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;","names":[]}

package/dist/chunk-YGUNJGP7.js

@@ -0,0 +1,23 @@
+import {
+  allowService
+} from "./chunk-NKTNTBOY.js";
+
+// src/policies/bun.ts
+var BUN_DOMAINS = ["bun.sh", "bun.com"];
+function bun() {
+  return {
+    id: "bun",
+    name: "Bun",
+    description: "Allow outbound access to Bun install and distribution endpoints.",
+    domains: BUN_DOMAINS
+  };
+}
+function allowBun() {
+  return allowService(bun());
+}
+
+export {
+  bun,
+  allowBun
+};
+//# sourceMappingURL=chunk-YGUNJGP7.js.map

package/dist/chunk-YGUNJGP7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/policies/bun.ts"],"sourcesContent":["import { allowService } from \"./dsl.ts\";\nimport type { PolicyServiceDescriptor, WorkspacePolicy } from \"./types.ts\";\n\nconst BUN_DOMAINS = [\"bun.sh\", \"bun.com\"] as const;\n\n/**\n * Allow outbound access to Bun distribution and install endpoints.\n */\nexport function bun(): PolicyServiceDescriptor {\n  return {\n    id: \"bun\",\n    name: \"Bun\",\n    description: \"Allow outbound access to Bun install and distribution endpoints.\",\n    domains: BUN_DOMAINS,\n  };\n}\n\nexport function allowBun(): WorkspacePolicy {\n  return allowService(bun());\n}\n"],"mappings":";;;;;AAGA,IAAM,cAAc,CAAC,UAAU,SAAS;AAKjC,SAAS,MAA+B;AAC7C,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,MAAM;AAAA,IACN,aAAa;AAAA,IACb,SAAS;AAAA,EACX;AACF;AAEO,SAAS,WAA4B;AAC1C,SAAO,aAAa,IAAI,CAAC;AAC3B;","names":[]}

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-import { S as SandkitOptions, a as SandboxDriverFactory, C as CommandResult, b as SandboxRunCommandOptions, W as WorkspaceSessionProcess, c as WorkspaceSessionProcessStartInput, d as WorkspaceSandboxLease, e as WorkspaceCreateOptions } from './types-B5N9o-ew.js';
+import { S as SandkitOptions, a as SandboxDriverFactory, C as CommandResult, W as WorkspaceRunCommandOptions, b as WorkspaceRunCommandDetachedOptions, c as Command, d as WorkspaceSessionRunCommandOptions, e as WorkspaceSessionProcess, f as WorkspaceSessionProcessStartInput, g as WorkspaceSandboxLease, h as WorkspaceCreateOptions } from './types-nu3vpBCZ.js';
 import { W as WorkspacePolicy, P as PolicyServiceDescriptor } from './types-Dpr_BkF9.js';
 export { a as PolicyServiceCredentialSource } from './types-Dpr_BkF9.js';
 export { aiGateway } from './policies/ai-gateway.js';
+export { allowBun, bun } from './policies/bun.js';
 export { codex } from './policies/codex.js';
 export { gemini } from './policies/gemini.js';
-export { S as SharedSetup } from './types-BRMAvcWc.js';
+export { allowNpm, npm } from './policies/npm.js';
+export { S as SharedSetup } from './types-DNpj280o.js';
 
 interface SandkitContext {
     readonly adapter: NonNullable<SandkitOptions["database"]>;
@@ -14,7 +16,8 @@ interface SandkitContext {
 
 interface WorkspaceSandboxHandle {
     runCommand(command: string, args: string[]): Promise<CommandResult>;
-    runCommand(input: SandboxRunCommandOptions): Promise<CommandResult>;
+    runCommand(input: WorkspaceRunCommandOptions): Promise<CommandResult>;
+    runCommand(input: WorkspaceRunCommandDetachedOptions): Promise<Command>;
     /**
      * Opens a live sandbox lease. timeoutMs overrides the provider's default
      * lease timeout for this session start; it does not change runCommand()
@@ -28,7 +31,7 @@ interface WorkspaceSandboxHandle {
 }
 interface WorkspaceSessionHandle {
     exec(command: string, args: string[]): Promise<CommandResult>;
-    exec(input: SandboxRunCommandOptions): Promise<CommandResult>;
+    exec(input: WorkspaceSessionRunCommandOptions): Promise<CommandResult>;
     commit(): Promise<void>;
     /**
      * Sets a non-durable, session-scoped policy override for subsequent session
@@ -60,6 +63,7 @@ declare class Sandkit {
     #private;
     constructor(options: SandkitOptions);
     get context(): SandkitContext;
+    bootstrap(): Promise<void>;
     createWorkspace(input?: WorkspaceCreateOptions): Promise<PublicWorkspaceHandle>;
     getWorkspace(id: string): Promise<PublicWorkspaceHandle>;
 }
@@ -75,4 +79,4 @@ interface GithubOptions {
 }
 declare function github(options?: GithubOptions): PolicyServiceDescriptor;
 
-export { PolicyServiceDescriptor, type PublicWorkspaceHandle, Sandkit, SandkitOptions, WorkspaceCreateOptions, type WorkspaceDescriptor, WorkspacePolicy, type WorkspaceSandboxHandle, type WorkspaceSessionHandle, type WorkspaceStatus, allowAll, allowService, allowServices, createSandkit, denyAll, github };
+export { Command, CommandResult, PolicyServiceDescriptor, type PublicWorkspaceHandle, Sandkit, SandkitOptions, WorkspaceCreateOptions, type WorkspaceDescriptor, WorkspacePolicy, WorkspaceRunCommandDetachedOptions, WorkspaceRunCommandOptions, type WorkspaceSandboxHandle, type WorkspaceSessionHandle, WorkspaceSessionRunCommandOptions, type WorkspaceStatus, allowAll, allowService, allowServices, createSandkit, denyAll, github };