> ## 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.

# Architecture

> Monorepo layout, package dependencies, and data flow.

## Monorepo structure

```
toolshed/
  apps/
    cli/          CLI tool (login, run, serve)
    server/       API backend (Hono + Vercel + Neon PostgreSQL)
    web/          Static landing page
  packages/
    kernel/       Runtime abstraction (local, Vercel, sandboxed JS)
    mcp-host/     MCP server hosting layer
    policy/       Authorization and consent engine
    sdk/          Plugin and tool definition SDK
    shared/       Shared types and Zod schemas
    sources/      Data source adapters (OpenAPI, MCP, GraphQL, plugins)
  plugins/
    github/       GitHub API integration
    google-workspace/  Gmail, Drive, Calendar
    linear/       Linear issue tracking
    slack/        Slack messaging
```

## Package dependency graph

```
cli ────→ kernel ────→ policy ────→ shared
  │         │
  ├──────→ mcp-host ──→ kernel
  │
  ├──────→ policy
  └──────→ shared

server ──→ sdk ────────→ shared
  │         │
  ├──────→ sources ────→ sdk
  │                       │
  ├──────→ policy         └──→ shared
  └──────→ shared

plugins (github, linear, google-workspace, slack)
  ├──────→ sdk ──────────→ shared
  └──────→ shared
```

## Data flow

The typical request flow when an agent executes a tool:

```
MCP Client (Claude, Cursor, etc.)
  │
  │  MCP protocol (stdio)
  ▼
MCP Host (mcp-host)
  │  creates McpServer with 4 tools
  ▼
Runtime (kernel)
  │  executes TypeScript in sandbox
  │  provides tools.* proxy namespace
  ▼
Tool Proxy (kernel/proxy)
  │  translates tools.github.issues.list({...})
  │  into invoke("github.issues.list", args)
  ▼
Elicitation Engine (kernel)
  │  if destructive: pause, wait for approval
  ▼
Plugin Handler / Source Adapter
  │  calls external API (GitHub, Slack, etc.)
  ▼
External Service
```

## Server architecture

The API server is built with [Hono](https://hono.dev/) and deployed to Vercel. It exposes six route groups under `/api`:

| Route group        | Purpose                                    |
| ------------------ | ------------------------------------------ |
| `/api/auth`        | OAuth2 login, callback, token storage      |
| `/api/tokens`      | Vend short-lived access tokens for plugins |
| `/api/registry`    | Tool catalog, source registration, search  |
| `/api/policy`      | Role management and access resolution      |
| `/api/audit`       | Audit trail for tool invocations           |
| `/api/elicitation` | Pending approval storage and resolution    |

All routes except health check and OAuth flow endpoints require a Bearer token in the `Authorization` header.

## Runtime backends

| Runtime         | Isolation                              | Use case                                       |
| --------------- | -------------------------------------- | ---------------------------------------------- |
| `RuntimeLocal`  | None (in-process `new Function()`)     | Local development with trusted scripts         |
| `RuntimeVercel` | Firecracker microVM via Vercel Sandbox | Production with untrusted agent-generated code |