Sessions
Session methods, input and event contracts, seeds, recorders, deferred work, and observers.
Session
Access: @nylorun/harness → Session
| Member | Parameters or type | Returns | Description |
|---|---|---|---|
id | string | — | Session identifier. |
state | SessionSnapshot | — | Current lifecycle state, transcript, pending interaction, and active work. |
input(event, options?) | SessionInput, optional InputOptions | InputHandle | Submits user text or a correlated approval/response reply. |
interrupt(event, options?) | MessageInput, optional InputOptions | InputHandle | Submits barge-in text. |
continue(options?) | optional InputOptions | InputHandle | Continues deferred work. |
stream() | None | AsyncIterable<SessionEvent> | Reads normalized session events. |
observe(listener) | Observer | () => void | Subscribes to live lifecycle observations; returns an unsubscribe function. |
stop(reason?) | optional string | Promise<void> | Stops the session. |
InputOptions has an optional signal: AbortSignal. InputHandle has an inputId and a
completed promise resolving to InputCompletion with its final status and emitted events.
Run options and seeds
Access: @nylorun/harness → SessionRunOptions, SessionOptions, SeededSessionOptions,
SessionSeed
| Name | Type | Required | Description |
|---|---|---|---|
SessionOptions.id | string | No | Host-assigned session id; Harness generates one when omitted. |
SessionOptions.userId | string | No | Host-owned user identity. |
SessionOptions.context | JsonObject | No | Host-owned JSON session context. |
SessionOptions.recorder | SessionRecorder | No | Receives each canonical session transition. |
SeededSessionOptions.seed | SessionSeed | Yes | Restores identity, counters, and canonical transcript. |
SeededSessionOptions.recorder | SessionRecorder | No | Records transitions after reconstruction. |
A seed can contain id, userId, context, turnCount, revision, and required transcript.
Do not mix seeded options with top-level id, userId, or context.
Inputs, snapshots, and records
Access: @nylorun/harness → SessionInput, MessageInput, InteractionReply,
SessionSnapshot, SessionRecord, SessionRecorder
| Type | Fields or variants | Description |
|---|---|---|
MessageInput | text string, or text plus optional JSON metadata | Ordinary user message. |
InteractionReply | approve or respond input event | Correlated reply to a required interaction. |
SessionSnapshot | id, status, turn count, revision, transcript, pending interaction, active work | Current in-memory state. |
SessionRecord | version, revision, transition, session, transcript, optional active record | Canonical persistence record for one transition. |
SessionRecorder | record(value: SessionRecord) | Host persistence callback. |
Events and active execution
Access: @nylorun/harness → SessionEvent, ObserveEvent, ActiveExecutionRecord,
ActiveModelExecutionRecord, ActiveToolsExecutionRecord, ActiveInteractionExecutionRecord
| Event or record | Description |
|---|---|
SessionEvent | Normalized input, candidate, final, interaction-required, tripwire, deferred, queue, rejection, cancellation, and stopped events. |
ObserveEvent | Detailed live lifecycle observations for configuration, model, middleware, tools, interactions, recording, and stopping. |
ActiveModelExecutionRecord | Active model invocation and the projected call. |
ActiveToolsExecutionRecord | Active tool-call set and individual settlement state. |
ActiveInteractionExecutionRecord | Pending interaction plus resumable tool execution. |
Every active record includes the ids necessary for durable host persistence. Deferred outcomes may
add a JSON token that the host uses to correlate external work before calling continue().