Skip to content
zidane
SDK reference

zidane/output/stream-json

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

import { … } from 'zidane/output/stream-json'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.

TypeScript
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#

createStreamJsonOutputHandlerFunction#

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

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

Parameters

Parameters
NameTypeDefaultDescription
options?StreamJsonOutputOptions{}

Output and line shape options.

Returns

(event: HeadlessEvent) => void

src/output/stream-json.ts:126

formatStreamJsonResultFunction#

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

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

Parameters

Parameters
NameTypeDefaultDescription
resultHeadlessResult

The headless run result.

options?StreamJsonFormatOptions{}

Line shape options.

src/output/stream-json.ts:101

formatStreamJsonTurnEventFunction#

Formats one turn event as a JSON-serializable value.

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

Parameters

Parameters
NameTypeDefaultDescription
event{ index: number; turn: SessionTurn; type: 'turn' }

The turn event.

options?StreamJsonFormatOptions{}

Line shape options.

src/output/stream-json.ts:75

setupStreamJsonOutputFunction#

Writes a JSONL line for every turn the agent persists.

Returns a function that detaches the output from the agent.

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

Parameters

Parameters
NameTypeDefaultDescription
agentAgent

Agent to listen to.

options?StreamJsonOutputOptions{}

Output and line shape options.

Returns

() => void

Example

Example
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()

src/output/stream-json.ts:157

streamJsonResultToJsonlFunction#

Formats a final headless result as a JSONL line.

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

Parameters

Parameters
NameTypeDefaultDescription
resultHeadlessResult

The headless run result.

options?StreamJsonFormatOptions{}

Line shape options.

Returns

string

src/output/stream-json.ts:114

streamJsonTurnEventToJsonlFunction#

Formats one turn event as a JSONL line.

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

Parameters

Parameters
NameTypeDefaultDescription
event{ index: number; turn: SessionTurn; type: 'turn' }

The turn event.

options?StreamJsonFormatOptions{}

Line shape options.

Returns

string

src/output/stream-json.ts:88

Interfaces#

StreamJsonFormatOptionsInterface#

Options that control the shape of each emitted line.

TypeScript
interface StreamJsonFormatOptions

Properties

StreamJsonFormatOptions properties
NameTypeDefaultDescription
format?HeadlessOutputFormat'zidane'

Line shape.

providerName?string'openai'

Provider name that selects the message shape when format is provider. anthropic gives Anthropic messages, anything else OpenAI messages.

src/output/stream-json.ts:34

StreamJsonOutputOptionsInterface#

Options for createStreamJsonOutputHandler and setupStreamJsonOutput.

TypeScript
interface StreamJsonOutputOptions extends StreamJsonFormatOptions

Properties

StreamJsonOutputOptions properties
NameTypeDefaultDescription
format?from StreamJsonFormatOptionsHeadlessOutputFormat'zidane'

Line shape.

providerName?from StreamJsonFormatOptionsstring'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.

src/output/stream-json.ts:50

Types#

StreamJsonOutputFormatType#

Line shape: zidane event envelopes or raw provider messages.

TypeScript
type StreamJsonOutputFormat = HeadlessOutputFormat

src/output/stream-json.ts:29

StreamJsonTurnEventType#

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

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

src/output/stream-json.ts:31