Skip to content
zidane
UI kit reference

zidane-ui/session/testing/contract

import { … } from 'zidane-ui/session/testing/contract'ui/src/session/testing/contract.ts

Functions#

describeSessionHostContractFunction#

Declares the shared SessionHost suite for one implementation.

TypeScript
function describeSessionHostContract(
  name: string,
  makeHarness: SessionHostHarnessFactory,
  capabilities: readonly SessionHostCapability[],
): void

Parameters

Parameters
NameTypeDescription
namestring

The implementation's name, shown in the suite title.

makeHarnessSessionHostHarnessFactory

Builds a fresh host over a backend that holds what it is given, once per test.

capabilitiesreadonly SessionHostCapability[]

The optional members the host offers. Every other optional member must be undefined.

ui/src/session/testing/contract.ts:315

Interfaces#

SessionHostContractBackendInterface#

What the backend behind the host holds, per session id.

TypeScript
interface SessionHostContractBackend

Properties

SessionHostContractBackend properties
NameTypeDescription
artifactsReadonly<Record<string, readonly SessionArtifact[]>>

The stored artifacts per session, newest first.

queueReadonly<Record<string, readonly SessionHostContractEntry[]>>

The queue per session.

scheduleFiresReadonly<Record<string, readonly ScheduleFire[]>>

Each reminder's fires, newest first.

schedulesreadonly Schedule[]

The stored reminders, oldest first (the Reminders setting is on). Serve them as createFixtureScheduleBackend does.

secretsReadonly<Record<string, readonly SessionSecretEntry[]>>

The saved secrets per session (its project's), without values.

sidesRecord<string, string>

Each session's side chat, by the parent's id: side chats created land here, removed ones leave.

todosReadonly<Record<string, readonly TodoItem[]>>

Each session's task list as the agent wrote it (todowrite): its applying plan. A session missing here holds no plans (its snapshot reads null). createFixturePlansBackend({ todos }) serves it.

turnsReadonly<Record<string, readonly SessionTurn[]>>

The stored turns per session.

workReadonly<Record<string, readonly RunningWorkItem[]>>

The running work per session.

ui/src/session/testing/contract.ts:148

SessionHostContractControlInterface#

Changes the backend from outside and announces it as the backend does.

TypeScript
interface SessionHostContractControl

Properties

SessionHostContractControl properties
NameTypeDescription
recordArtifact(sessionId: string, artifact: SessionArtifact) => void

The session recorded an artifact (it becomes the newest).

setQueue(sessionId: string, entries: readonly SessionHostContractEntry[]) => void

Another window changed the session's queue.

setSchedules?(list: readonly Schedule[]) => void

The stored reminders changed (the agent set one, one fired): announced as schedules:changed. Absent: not checked.

setSecrets(sessionId: string, entries: readonly SecretEntry[]) => void

The session's project secrets changed (the agent saved one, another window revoked one): announced as a store change.

setWork(sessionId: string, items: readonly RunningWorkItem[]) => void

The session's work changed (a tool call started or ended).

writeTodos(sessionId: string, items: readonly TodoItem[]) => void

The agent wrote its task list again (todowrite): announced as a plans snapshot.

ui/src/session/testing/contract.ts:173

SessionHostContractEntryInterface#

A queued message the backend holds, with its attachments' bytes.

TypeScript
interface SessionHostContractEntry

Properties

SessionHostContractEntry properties
NameTypeDescription
attachments?PromptAttachment[]

Its attachments, with their bytes.

idstring

The entry's id.

textstring

The message text.

ui/src/session/testing/contract.ts:138

SessionHostHarnessInterface#

A host built over a backend, the backend's control, and how to tear them down.

TypeScript
interface SessionHostHarness

Properties

SessionHostHarness properties
NameTypeDescription
controlSessionHostContractControl

Changes the backend from outside.

hostSessionHost

The host under test.

dispose?() => void

Closes connections and timers after each test.

ui/src/session/testing/contract.ts:189

Types#

SessionHostCapabilityType#

An optional SessionHost member, by its path.

TypeScript
type SessionHostCapability =
  | 'plans'
  | 'plans.edit'
  | 'plans.control'
  | 'plans.retry'
  | 'queue'
  | 'queue.add'
  | 'queue.remove'
  | 'queue.update'
  | 'queue.attachments'
  | 'queue.pushNow'
  | 'artifacts'
  | 'artifacts.remove'
  | 'artifacts.refreshRow'
  | 'runningWork'
  | 'runningWork.cancel'
  | 'turns'
  | 'turns.fork'
  | 'turns.editText'
  | 'turns.delete'
  | 'turns.rewind'
  | 'details'
  | 'details.titleStatus'
  | 'details.generateTitle'
  | 'details.export'
  | 'details.compact'
  | 'details.setFolder'
  | 'details.cacheReport'
  | 'usage'
  | 'usage.summary'
  | 'usage.providers'
  | 'usage.github'
  | 'usage.redeemReset'
  | 'side'
  | 'side.subscribe'
  | 'secrets'
  | 'secrets.save'
  | 'secrets.revoke'
  | 'schedules'
  | 'schedules.create'
  | 'schedules.update'
  | 'schedules.remove'
  | 'schedules.runNow'
  | 'schedules.fires'

ui/src/session/testing/contract.ts:46

SessionHostHarnessFactoryType#

Builds a fresh host (and its backend) for one test.

TypeScript
type SessionHostHarnessFactory = (backend: SessionHostContractBackend) => SessionHostHarness | Promise<SessionHostHarness>

ui/src/session/testing/contract.ts:199