> ## 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/shared

> Shared types, Zod schemas, and utility functions.

The shared package provides the common type definitions, validation schemas, and utility functions used across all Toolshed packages.

## Schemas

See [Schema Reference](/reference/schemas) for the complete field-by-field documentation.

| Schema                      | Description                                     |
| --------------------------- | ----------------------------------------------- |
| `ToolDefinitionSchema`      | Tool with path, name, schemas, destructive flag |
| `RoleSchema`                | Role with ID, name, and glob patterns           |
| `AuditEntrySchema`          | Audit trail entry                               |
| `ElicitationRequestSchema`  | Pending approval request                        |
| `ElicitationResponseSchema` | Approval response with `approved` boolean       |
| `SerializedCatalogSchema`   | Wire format for the tool catalog                |
| `ToolRegistrationSchema`    | Tool entry in the catalog                       |
| `SourceRegistrationSchema`  | Source entry in the catalog                     |
| `RunRequestSchema`          | Script execution request                        |
| `SearchToolsRequestSchema`  | Tool search request                             |
| `ReadToolRequestSchema`     | Tool lookup request                             |
| `ResumeRequestSchema`       | Elicitation resume request                      |

## Types

| Type                  | Inferred from               | Description          |
| --------------------- | --------------------------- | -------------------- |
| `ToolDefinition`      | `ToolDefinitionSchema`      | A registered tool    |
| `Role`                | `RoleSchema`                | A user role          |
| `AuditEntry`          | `AuditEntrySchema`          | An audit log entry   |
| `ElicitationRequest`  | `ElicitationRequestSchema`  | An approval request  |
| `ElicitationResponse` | `ElicitationResponseSchema` | An approval response |

## Interfaces

| Interface        | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| `PluginManifest` | Plugin metadata: id, name, description, tools, authProviders |
| `AuthProvider`   | Auth config: id, type, provider, scopes                      |
| `PluginContext`  | Handler context: userId, role, auth, elicit, logger          |
| `AuthResolver`   | `getToken(provider): Promise<string>`                        |
| `ElicitFn`       | `(request) => Promise<ElicitationResponse>`                  |
| `Logger`         | `info()`, `warn()`, `error()` with optional metadata         |

See [PluginContext Reference](/reference/plugin-context) for full details.

## Utility functions

### `serializeCatalog(tools, sources): SerializedCatalog`

Serializes tools and sources into the wire format, deduplicating JSON Schema objects into a shared type dictionary.

### `deserializeCatalog(catalog): { tools, sources }`

Deserializes the wire format back into `ToolDefinition[]` and `SourceRegistration[]`.

### `searchTools(tools, query, limit?): ToolDefinition[]`

Weighted fuzzy search across tool paths, names, and descriptions. Uses AND semantics for multi-token queries.