@sandblocks/sdk 0.1.0

package/dist/types/types.d.ts

@@ -0,0 +1,196 @@
+export interface SandboxCapabilities {
+    bindMounts: boolean;
+    isolatedFilesystem: boolean;
+    persistent: boolean;
+    networks: boolean;
+    devices: boolean;
+    snapshots: boolean;
+    reconnect: boolean;
+    remote: boolean;
+}
+export interface SandboxMount {
+    source?: string;
+    resource?: string;
+    target: string;
+    readonly?: boolean;
+}
+export interface SandboxCreateInput {
+    id: string;
+    cwd: string;
+    image?: string;
+    env?: Record<string, string>;
+    mounts?: SandboxMount[];
+    network?: string | string[];
+    groups?: Array<string | number>;
+    devices?: string[];
+    cpus?: number;
+    memoryMb?: number;
+    pids?: number;
+    tmpfsMb?: number;
+    signal?: AbortSignal;
+    idempotencyKey?: string;
+    metadata?: Record<string, string>;
+}
+export interface SandboxReconnectInput {
+    id: string;
+    cwd?: string;
+    signal?: AbortSignal;
+}
+export interface SandboxExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onStdout?: (chunk: string) => void | Promise<void>;
+    onStderr?: (chunk: string) => void | Promise<void>;
+}
+export interface SandboxExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    startedAt: string;
+    finishedAt: string;
+}
+export interface SandboxRuntime {
+    readonly id: string;
+    readonly provider: string;
+    readonly cwd: string;
+    exec(command: string[], options?: SandboxExecOptions): Promise<SandboxExecResult>;
+    upload?(source: string, destination: string): Promise<void>;
+    download?(source: string, destination: string): Promise<void>;
+    /** Reconcile isolated-provider changes back into the host worktree. */
+    syncToHost?(): Promise<void>;
+    stop(reason?: string): Promise<void>;
+    destroy(): Promise<void>;
+}
+export interface SandboxProvider {
+    readonly kind: string;
+    readonly capabilities: SandboxCapabilities;
+    create(input: SandboxCreateInput): Promise<SandboxRuntime>;
+    reconnect?(input: SandboxReconnectInput): Promise<SandboxRuntime>;
+}
+export type AgentStreamEvent = {
+    type: "text";
+    text: string;
+    iteration: number;
+    timestamp: string;
+} | {
+    type: "toolCall";
+    name: string;
+    input?: unknown;
+    iteration: number;
+    timestamp: string;
+} | {
+    type: "raw";
+    line: string;
+    iteration: number;
+    timestamp: string;
+};
+export interface AgentContext {
+    runtime: SandboxRuntime;
+    prompt: string;
+    iteration: number;
+    signal?: AbortSignal;
+    emit(event: AgentStreamEvent): Promise<void>;
+    idleTimeoutSeconds: number;
+    completionTimeoutSeconds: number;
+    completionSignal: string[];
+}
+export interface AgentIterationResult {
+    iteration: number;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    sessionId?: string;
+    completionSignal?: string;
+    startedAt: string;
+    finishedAt: string;
+}
+export interface AgentProvider {
+    readonly id: string;
+    run(context: AgentContext): Promise<AgentIterationResult>;
+}
+export interface CommandHook {
+    command?: string[];
+    shell?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+}
+export interface RunHooks {
+    host?: {
+        beforeCreate?: CommandHook[];
+        onWorktreeReady?: CommandHook[];
+        onSandboxReady?: CommandHook[];
+        afterCreate?: CommandHook[];
+        beforeDestroy?: CommandHook[];
+    };
+    sandbox?: {
+        onSandboxReady?: CommandHook[];
+        afterCreate?: CommandHook[];
+        beforeAgent?: CommandHook[];
+        afterAgent?: CommandHook[];
+    };
+}
+export type BranchStrategy = {
+    type: "head";
+} | {
+    type: "branch";
+    name: string;
+} | {
+    type: "worktree";
+    name: string;
+} | {
+    type: "merge-to-head";
+    name?: string;
+};
+export type RetentionPolicy = "destroy" | "on-failure" | "always";
+export interface LoggingOptions {
+    type?: "file" | "stdout" | "silent";
+    path?: string;
+    verbose?: boolean;
+    onAgentStreamEvent?: (event: AgentStreamEvent) => void | Promise<void>;
+}
+export interface StandardSchema<T> {
+    readonly "~standard"?: {
+        validate(value: unknown): {
+            value?: T;
+            issues?: readonly unknown[];
+        } | Promise<{
+            value?: T;
+            issues?: readonly unknown[];
+        }>;
+    };
+    parse?: (value: unknown) => T;
+    safeParse?: (value: unknown) => {
+        success: boolean;
+        data?: T;
+        error?: unknown;
+    };
+}
+export type OutputSpec<T = unknown> = {
+    kind: "string";
+    tag: string;
+} | {
+    kind: "object";
+    tag: string;
+    schema: StandardSchema<T>;
+};
+export interface CommitInfo {
+    sha: string;
+    message?: string;
+}
+export interface AgentRunResult<T = unknown> {
+    sandboxId: string;
+    provider: string;
+    iterations: AgentIterationResult[];
+    commits: CommitInfo[];
+    branch?: string;
+    completionSignal?: string;
+    output?: T;
+    startedAt: string;
+    finishedAt: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@sandblocks/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/types/index.d.ts",
+  "bin": { "sandblocks-sdk": "dist/bin.js" },
+  "files": ["dist", "README.md"],
+  "exports": {
+    ".": { "types": "./dist/types/index.d.ts", "import": "./dist/index.js" },
+    "./agents": {
+      "types": "./dist/types/agents.d.ts",
+      "import": "./dist/agents.js"
+    },
+    "./output": {
+      "types": "./dist/types/output.d.ts",
+      "import": "./dist/output.js"
+    },
+    "./providers/docker": {
+      "types": "./dist/types/providers/docker.d.ts",
+      "import": "./dist/providers/docker.js"
+    },
+    "./providers/podman": {
+      "types": "./dist/types/providers/podman.d.ts",
+      "import": "./dist/providers/podman.js"
+    },
+    "./providers/remote": {
+      "types": "./dist/types/providers/remote.d.ts",
+      "import": "./dist/providers/remote.js"
+    },
+    "./providers/unsafe-host": {
+      "types": "./dist/types/providers/unsafe-host.d.ts",
+      "import": "./dist/providers/unsafe-host.js"
+    },
+    "./providers/custom": {
+      "types": "./dist/types/providers/custom.d.ts",
+      "import": "./dist/providers/custom.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts src/agents.ts src/output.ts src/providers/docker.ts src/providers/podman.ts src/providers/remote.ts src/providers/unsafe-host.ts src/providers/custom.ts src/bin.ts --outdir dist --root src --target=node --format=esm && bunx tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepack": "bun run build && bun run test"
+  },
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=20" }
+}