> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# @toolshed/kernel

> Runtime abstraction, elicitation engine, and tools proxy.

The kernel package provides the execution runtime, elicitation engine, and tools proxy that power Toolshed's sandboxed script execution.

## Runtime interface

```typescript theme={null}
interface Runtime {
  execute(script: string): Promise<ExecutionResult>;
  availableTools(): string[];
  dispose(): Promise<void>;
}
```

### ExecutionResult

```typescript theme={null}
interface ExecutionResult {
  success: boolean;
  value?: unknown;          // Return value from the script
  error?: string;           // Error message if failed
  calls: Array<{            // Tool calls made during execution
    path: string;
    args: Record<string, unknown>;
  }>;
  logs?: Array<{            // Console output
    level: string;
    message: string;
  }>;
  paused?: {                // Present when a destructive tool needs approval
    executionId: string;
    toolPath: string;
    message: string;
    args?: Record<string, unknown>;
  };
}
```

## Runtime implementations

### RuntimeLocal

In-process execution using `new Function()`. No isolation -- suitable only for local development with trusted scripts.

### RuntimeVercel

Production runtime using Vercel Sandbox (Firecracker microVMs). Provides full isolation with configurable resources.

```typescript theme={null}
interface VercelRuntimeConfig extends RuntimeConfig {
  teamId: string;
  projectId: string;
  token: string;
  snapshotId?: string;
  timeoutMs?: number;     // default: 300000 (5 min)
  vcpus?: number;         // default: 2
  networkPolicy?: NetworkPolicy;
}
```

## createRuntime(options)

Factory function that creates and configures a runtime:

```typescript theme={null}
import { createRuntime } from "@toolshed/kernel";

const runtime = createRuntime({
  tools: allTools,
  role: userRole,       // Tools are filtered by role
  invoke: toolInvoker,
  searchTools: searchFn,
  describeTools: describeFn,
  elicitation: engine,
  runtime: "local",     // or "vercel"
});
```

## ElicitationEngine

See the [Elicitation Guide](/guides/elicitation) for usage details.

## buildProxy(tools, invoke, searchTools?, describeTools?)

Builds the recursive ES Proxy that provides the `tools.*` namespace inside sandbox scripts.

* `tools.github.issues.list(args)` invokes tool path `github.issues.list`
* `tools.search({ query, limit? })` searches the catalog
* `tools.describe.tool({ path })` gets a tool's full definition
* Enumeration is blocked -- agents must use `tools.search()` to discover tools