SDK overview · Hay Docs

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.

Connect to the current task

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 maps each permission to its methods. APIs reject unavailable, revoked, or invalid requests; show those errors in the interface.

Read and save local state

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

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, injected client source, and standalone packager are published as readable source files. Reference notes explain how they are generated from the app.

Structural JSON schemas are available for manifests, bundles, and legacy registry indexes. Schemas also cover discovery, pages and direct releases. The registry contract 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.