# zidane/output/stream-json

> A JSONL writer that emits one line per persisted turn, for pipes, logs and other programs.

Import: `import { … } from 'zidane/output/stream-json'`. Source: [src/output/stream-json.ts](https://github.com/Tahul/zidane/blob/main/src/output/stream-json.ts).

Use `zidane/output/stream-json` when another process reads the run: a wrapper script, a log shipper or an eval harness. `setupStreamJsonOutput()` writes one JSON line per turn the agent persists, either as `zidane` event envelopes or as raw provider messages. The format helpers build the same lines without attaching to an agent, and `createStreamJsonOutputHandler()` fits the headless runner.

```ts
import { createAgent } from 'zidane'
import { setupStreamJsonOutput } from 'zidane/output/stream-json'
import { basic } from 'zidane/presets'
import { anthropic } from 'zidane/providers/anthropic'

const agent = createAgent({ ...basic, provider: anthropic() })
const lines: string[] = []
const stop = setupStreamJsonOutput(agent, { format: 'zidane', write: line => lines.push(line) })

await agent.run({ prompt: 'Say hello.' })
stop()
console.log(lines.length)
```

## Functions

### `createStreamJsonOutputHandler`

Function.

Creates a headless event handler that writes one JSONL line per `turn` event and ignores other events.

```ts
function createStreamJsonOutputHandler(
  options?: StreamJsonOutputOptions,
): (event: HeadlessEvent) => void
```

**Parameters**

- `options?` (`StreamJsonOutputOptions`, default `{}`): Output and line shape options.

**Returns** `(event: HeadlessEvent) => void`

Source: [src/output/stream-json.ts:126](https://github.com/Tahul/zidane/blob/main/src/output/stream-json.ts#L126)

### `formatStreamJsonResult`

Function.

Formats a final headless result as a JSON-serializable value.

```ts
function formatStreamJsonResult(
  result: HeadlessResult,
  options?: StreamJsonFormatOptions,
): FormattedHeadlessResult
```

**Parameters**

- `result` (`HeadlessResult`): The headless run result.
- `options?` (`StreamJsonFormatOptions`, default `{}`): Line shape options.

**Returns** `FormattedHeadlessResult`

Source: [src/output/stream-json.ts:101](https://github.com/Tahul/zidane/blob/main/src/output/stream-json.ts#L101)

### `formatStreamJsonTurnEvent`

Function.

Formats one `turn` event as a JSON-serializable value.

```ts
function formatStreamJsonTurnEvent(
  event: { index: number; turn: SessionTurn; type: 'turn' },
  options?: StreamJsonFormatOptions,
): FormattedHeadlessTurnEvent
```

**Parameters**

- `event` (`{ index: number; turn: SessionTurn; type: 'turn' }`): The turn event.
- `options?` (`StreamJsonFormatOptions`, default `{}`): Line shape options.

**Returns** `FormattedHeadlessTurnEvent`

Source: [src/output/stream-json.ts:75](https://github.com/Tahul/zidane/blob/main/src/output/stream-json.ts#L75)

### `setupStreamJsonOutput`

Function.

Writes a JSONL line for every turn the agent persists.

Returns a function that detaches the output from the agent.

```ts
function setupStreamJsonOutput(
  agent: Agent,
  options?: StreamJsonOutputOptions,
): () => void
```

**Parameters**

- `agent` (`Agent`): Agent to listen to.
- `options?` (`StreamJsonOutputOptions`, default `{}`): Output and line shape options.

**Returns** `() => void`

**Example**

```ts
import { createAgent } from 'zidane'
import { basic } from 'zidane/presets'
import { anthropic } from 'zidane/providers'
import { setupStreamJsonOutput } from 'zidane/output/stream-json'

const agent = createAgent({ ...basic, provider: anthropic({ apiKey: 'sk-ant-...' }) })
const stop = setupStreamJsonOutput(agent, { format: 'zidane' })
await agent.run({ prompt: 'build a REST API' })
stop()
```

Source: [src/output/stream-json.ts:157](https://github.com/Tahul/zidane/blob/main/src/output/stream-json.ts#L157)

### `streamJsonResultToJsonl`

Function.

Formats a final headless result as a JSONL line.

```ts
function streamJsonResultToJsonl(
  result: HeadlessResult,
  options?: StreamJsonFormatOptions,
): string
```

**Parameters**

- `result` (`HeadlessResult`): The headless run result.
- `options?` (`StreamJsonFormatOptions`, default `{}`): Line shape options.

**Returns** `string`

Source: [src/output/stream-json.ts:114](https://github.com/Tahul/zidane/blob/main/src/output/stream-json.ts#L114)

### `streamJsonTurnEventToJsonl`

Function.

Formats one `turn` event as a JSONL line.

```ts
function streamJsonTurnEventToJsonl(
  event: { index: number; turn: SessionTurn; type: 'turn' },
  options?: StreamJsonFormatOptions,
): string
```

**Parameters**

- `event` (`{ index: number; turn: SessionTurn; type: 'turn' }`): The turn event.
- `options?` (`StreamJsonFormatOptions`, default `{}`): Line shape options.

**Returns** `string`

Source: [src/output/stream-json.ts:88](https://github.com/Tahul/zidane/blob/main/src/output/stream-json.ts#L88)

## Interfaces

### `StreamJsonFormatOptions`

Interface.

Options that control the shape of each emitted line.

```ts
interface StreamJsonFormatOptions
```

**Properties**

- `format?` (`HeadlessOutputFormat`, default `'zidane'`): Line shape.
- `providerName?` (`string`, default `'openai'`): Provider name that selects the message shape when `format` is `provider`. `anthropic` gives Anthropic messages, anything else OpenAI messages.

Source: [src/output/stream-json.ts:34](https://github.com/Tahul/zidane/blob/main/src/output/stream-json.ts#L34)

### `StreamJsonOutputOptions`

Interface.

Options for [`createStreamJsonOutputHandler`](https://zidane.si/docs/reference/output-stream-json.md#createStreamJsonOutputHandler) and [`setupStreamJsonOutput`](https://zidane.si/docs/reference/output-stream-json.md#setupStreamJsonOutput).

```ts
interface StreamJsonOutputOptions extends StreamJsonFormatOptions
```

**Properties**

- `format?` (`HeadlessOutputFormat`, from `StreamJsonFormatOptions`, default `'zidane'`): Line shape.
- `providerName?` (`string`, from `StreamJsonFormatOptions`, default `'openai'`): Provider name that selects the message shape when `format` is `provider`. `anthropic` gives Anthropic messages, anything else OpenAI messages.
- `write?` (`(line: string) => void`): Receives each JSONL line. Default: writes to `process.stdout`.

Source: [src/output/stream-json.ts:50](https://github.com/Tahul/zidane/blob/main/src/output/stream-json.ts#L50)

## Types

### `StreamJsonOutputFormat`

Type.

Line shape: `zidane` event envelopes or raw `provider` messages.

```ts
type StreamJsonOutputFormat = HeadlessOutputFormat
```

Source: [src/output/stream-json.ts:29](https://github.com/Tahul/zidane/blob/main/src/output/stream-json.ts#L29)

### `StreamJsonTurnEvent`

Type.

A complete `turn` event, the only event this output emits.

```ts
type StreamJsonTurnEvent = Extract<HeadlessEvent, { type: 'turn' }>
```

Source: [src/output/stream-json.ts:31](https://github.com/Tahul/zidane/blob/main/src/output/stream-json.ts#L31)