Shape

interface History {
  lastUser(): Message | null
  lastAssistant(): Message | null
  range(options: { fromEnd: number; toEnd: number }): Message[]
  recent(n: number): Message[]
  byTokens(maxTokens: number): Message[]
  recentText(n: number): string
}

interface Message {
  role: 'user' | 'assistant' | 'system'
  content: string | null
  attachments?: Attachment[]
}

interface Attachment {
  id: string
  name: string
  size: number
  modality: 'document' | 'image' | 'audio' | 'video'
  mimeType?: string
}

Methods

lastUser()

Returns the most recent user message in the conversation history.

If no user message exists, this returns null.

lastAssistant()

Returns the most recent assistant message in the conversation history.

If no assistant message exists, this returns null.

range( fromEnd, toEnd )

Selects a slice of messages relative to the end of the conversation history.

Messages are indexed from the end:

• 0 – most recent message
• 1 – previous message
• 2 – two messages back

The selection range is left-inclusive and right-exclusive:

[fromEnd, toEnd)

Constraints:

fromEnd > toEnd >= 0

The returned messages are always ordered from old → new.

recent(n)

Returns the latest n messages from the conversation history.

This is equivalent to:

ctx.history.range({ fromEnd: n, toEnd: 0 })

byTokens(maxTokens)

Selects messages from the end of the history until an approximate token budget is reached.

Messages are collected starting from the most recent message and walking backward until the estimated token limit is reached.

Returned messages are always ordered from old → new.

Messages that would exceed the token limit are not included.

recentText(n)

Returns a plain text representation of the latest n messages.

Attachments are converted into readable placeholders:

File: filename.ext

Example output:

User: Check this report
File: report.pdf

Assistant: The report looks correct.

This helper is useful when building prompts that only accept text.

Usage

Strategies can retrieve recent conversation history when building prompts:

const history = ctx.history.recent(10)

ctx.slots.add('history', history)

Strategies may also apply additional filtering:

const userMessages = ctx.history
  .recent(20)
  .filter(m => m.role === 'user')

Text-only prompts can use:

const textHistory = ctx.history.recentText(10)

Attachments in History

Attachments returned in Message.attachments are metadata references, not file contents.

They represent assets stored in AfferLab’s asset system.

During prompt rendering:

• attachments are converted into provider file references (for example file_id)
• a small text hint such as File: report.pdf may be inserted to preserve filename context

This allows strategies to include multimodal history without manually handling file uploads.

Notes

History selections operate on the conversation snapshot fetched by the host for the current turn.

All history helpers return message arrays that are safe to filter or transform inside strategy code.

Attachments in history are references to stored assets. File transfer and provider file reuse are handled by the host during prompt rendering.