---
title: Generation and outputs
description: Generate a result, save it with the task, and hand it to the next step.
group: Build
---

# Generation and outputs

Use direct generation when a plugin needs a result rather than an assistant tool loop. Generation and durable output storage are separate operations.

## Generate text or JSON

```js
const generated = await Hay.models.generate({
  prompt: 'Turn these notes into a concise implementation brief: ...',
  format: 'text'
});
```

`models.generate` requires `models.invoke`. It returns `{text, json?}`. Formats are `text` and `json`; malformed JSON rejects. Prompts are limited to 60,000 characters and a generation request has a three-minute timeout. The selected provider and retention policy apply.

## Save and read an output

```js
const saved = await Hay.outputs.create({
  title: 'Implementation brief',
  format: 'text',
  text: generated.text
});
const summaries = await Hay.outputs.list();
const full = await Hay.outputs.read(saved.id);
```

Outputs require `storage` and belong to the current plugin and task. Supported formats are `text`, `json`, and `coding-spec`. Text outputs use `text`; structured outputs use `data`.

Records are immutable. Hay assigns identity, ownership and creation time. A task can retain 100 outputs of up to 180 KB each. Outputs persist independently of the conversation.

## Hand off explicitly

```js
const targets = await Hay.outputs.targets();
// Let the user choose one of these destinations.
const selected = targets[0];
if (selected) {
  const copy = await Hay.outputs.handoff(saved.id, {
    kind: 'task', taskId: selected.taskId
  });
}
```

`targets()` lists other enabled tasks whose plugins have storage permission. `handoff` asks for review naming the output and destination, then creates an independent copy. The copy records `sharedFrom`. It does not start a model call or execute the receiving plugin.

Use `outputs.onChange(listener)` to refresh a task’s output library; it returns an unsubscribe function.

## Hand a spec to coding

```js
const output = await Hay.outputs.create({
  title: spec.title, format: 'coding-spec', data: spec
});
const job = await Hay.outputs.handoff(output.id, {kind: 'coding'});
```

A coding handoff also needs `coding.run`. It creates a native draft, without running code or granting repository access. Read [native coding](coding/) for execution, verification, and exact-diff review.