---
title: SDK overview
description: Use Hay’s services through a small, permissioned browser API.
group: Build
---

# SDK overview

Hay injects `window.Hay` before plugin scripts. Do not load a remote SDK script and do not import the desktop preload API. Hay account sign-in and publishing authority stay in the trusted host; there is no account-management SDK for plugin frames. The public TypeScript contract is in the [SDK source](https://github.com/use-hay/app/blob/main/packages/sdk/index.ts).

## Connect to the current task

```js
const context = await Hay.ready;
console.log(context.taskId, context.viewId, context.pinned);
const unsubscribe = Hay.onContext(next => {
  // Preserve in-progress edits when context is delivered again.
});
// Call unsubscribe() when disposing the view.
```

`Hay.context` holds the latest context after readiness. Views must be declared in the manifest. Context events can repeat as workspace state changes.

## Services at a glance

| Service | What it does | Required capability |
| --- | --- | --- |
| `storage.get`, `storage.set` | Read and save JSON in this plugin’s workspace namespace. | `storage` |
| `documents.list` | Read explicitly imported text documents. | `files.read` |
| `sources.list` | Read sources captured in this workspace for the plugin. | `storage` |
| `agent.run` | Start an assistant response in the current task. | `models.invoke` |
| `models.generate` | Generate a text or JSON result without a chat tool loop. | `models.invoke` |
| `outputs.*` | Save, read, and explicitly hand off task-owned outputs. | `storage` |
| `coding.*` | Create a scoped spec, request coding, inspect checks, review and request a commit. | Method-specific coding grants |
| `browser.*` | Open pages, observe task tabs, and request reviewed actions. | `browser.read` or `browser.control` |
| `github.readPullRequest` | Read an approved GitHub.com PR snapshot. | `github.read`; private reads also need `github.private.read` |

The [capability reference](capabilities/) maps each permission to its methods. APIs reject unavailable, revoked, or invalid requests; show those errors in the interface.

## Read and save local state

```js
await Hay.ready;
const notes = await Hay.storage.get('notes') ?? [];
await Hay.storage.set('notes', [...notes, {text: 'A useful observation'}]);
```

Keys belong to the plugin identity and workspace. The plugin chooses keys, never filesystem paths. Records survive a task switch. Use task-owned outputs for deliverables that should belong to one task rather than to the plugin as a whole.

## Render returned data safely

```js
const documents = await Hay.documents.list();
const list = document.querySelector('#documents');
for (const record of documents) {
  const item = document.createElement('li');
  item.textContent = record.name;
  list.append(item);
}
```

Treat document text, web pages, model output, and tool results as untrusted data. Render text with `textContent`, not by interpolating it into HTML. Data cannot grant a capability or instruct the host to bypass review.

## What the SDK does not expose

There is no arbitrary filesystem, shell, raw network, credential, cookie, permission-management, or native desktop-control API. Plugins run in an opaque-origin frame with restrictive content policies. Services are mediated by Hay’s capability broker.

`Hay.call` is the lower-level typed transport entry point, not a route around capabilities. Prefer the documented service methods. A method name sent by a plugin is still validated by the host.

## Contract files

The [SDK TypeScript declaration](reference/index.ts), [injected client source](reference/client.js), and [standalone packager](reference/build-plugin.mjs) are published as readable source files. [Reference notes](reference/README.md) explain how they are generated from the app.

Structural JSON schemas are available for [manifests](reference/manifest.schema.json), [bundles](reference/bundle.schema.json), and [legacy registry indexes](reference/registry.schema.json). Schemas also cover [discovery](reference/registry-discovery.schema.json), [pages](reference/registry-page.schema.json) and [direct releases](reference/registry-release.schema.json). The [registry contract](registry-reference/) describes base-address discovery, paged catalogs and direct release lookup. Those network operations belong to the trusted host, not the plugin SDK. A structurally valid object must still pass runtime checks for cross-field references, grants, ownership, source provenance, exact bytes, review and size limits.