@aparte/engine — API reference

Classes

ArtifactXmlStateMachine

Defined in: agent/parsers/artifact-xml-state-machine.ts:81

A stateful streaming parser for one turn’s <artifact> blocks. Feed it each text delta; drain the returned events. Call finalize when the stream ends to flush a truncated (unclosed) artifact.

Constructors

Constructor

new ArtifactXmlStateMachine(hint, idGen?): ArtifactXmlStateMachine;

Defined in: agent/parsers/artifact-xml-state-machine.ts:95

Parameters

Parameter	Type
`hint`	`XmlArtifactHint`
`idGen?`	() => `string`

Returns

ArtifactXmlStateMachine

Accessors

currentState

Get Signature

get currentState(): XmlArtifactState;

Defined in: agent/parsers/artifact-xml-state-machine.ts:178

Current parser state (for the adapter to decide finalize routing).

Returns

XmlArtifactState

Methods

feed()

feed(delta): XmlArtifactEvent[];

Defined in: agent/parsers/artifact-xml-state-machine.ts:100

Feed one text delta; returns the ordered micro-events it produced.

Parameters

Parameter	Type
`delta`	`string`

Returns

XmlArtifactEvent[]

finalize()

finalize(): XmlArtifactEvent[];

Defined in: agent/parsers/artifact-xml-state-machine.ts:165

Flush a truncated artifact: if the stream ended mid-body (model cut off before </artifact>), emit a close with whatever was buffered. Mirrors _streamLoop’s finalize block (:1658-1669).

Returns

XmlArtifactEvent[]

Interfaces

XmlArtifactHint

Defined in: agent/parsers/artifact-xml-state-machine.ts:24

Fallback mime/kind for an artifact whose open tag omits the attribute.

Properties

mimeType

mimeType: string;

Defined in: agent/parsers/artifact-xml-state-machine.ts:25

kind

kind: string;

Defined in: agent/parsers/artifact-xml-state-machine.ts:26

StreamUsage

Defined in: agent/stream-events.ts:33

Token usage. Structurally a superset-compatible mirror of AparteUsage: the five common fields plus an index signature that carries the provider-specific rest (ttft/decode/phases/…) opaquely — the loop transports usage, never reads past these five.

Indexable

[key: string]: unknown

Properties

inputTokens

inputTokens: number;

Defined in: agent/stream-events.ts:34

outputTokens

outputTokens: number;

Defined in: agent/stream-events.ts:35

totalTokens?

optional totalTokens?: number;

Defined in: agent/stream-events.ts:36

cacheReadTokens?

optional cacheReadTokens?: number;

Defined in: agent/stream-events.ts:37

durationMs?

optional durationMs?: number;

Defined in: agent/stream-events.ts:38

StreamToolCall

Defined in: agent/stream-events.ts:43

One tool call as surfaced by the provider stream (mirrors AparteToolCall).

Properties

id

id: string;

Defined in: agent/stream-events.ts:44

name

name: string;

Defined in: agent/stream-events.ts:45

input

input: unknown;

Defined in: agent/stream-events.ts:46

StreamAgentMessage

Defined in: agent/stream-events.ts:65

A conversation message (mirrors AparteChatMessage). role is left open (string) so the loop can push the 'tool_call' / 'tool_result' envelope roles _streamLoop uses without importing core’s union.

Indexable

[key: string]: unknown

Properties

role

role: string;

Defined in: agent/stream-events.ts:66

content

content: string;

Defined in: agent/stream-events.ts:67

toolCalls?

optional toolCalls?: StreamToolCall[];

Defined in: agent/stream-events.ts:69

Present on a 'tool_call' envelope — the whole turn’s calls, grouped.

toolCallId?

optional toolCallId?: string;

Defined in: agent/stream-events.ts:71

Present on a 'tool_result' message — which call it answers.

precedingText?

optional precedingText?: string;

Defined in: agent/stream-events.ts:73

Assistant text that preceded the tool call(s) this turn.

StreamChatRequest

Defined in: agent/stream-events.ts:78

The request handed to the transport each turn (mirrors AparteChatRequest).

Indexable

[key: string]: unknown

Properties

messages

messages: StreamAgentMessage[];

Defined in: agent/stream-events.ts:79

StreamToolConfig

Defined in: agent/stream-events.ts:90

Per-tool loop configuration (mirrors the AparteTool subset the loop reads).

Properties

maxTurns?

optional maxTurns?: number;

Defined in: agent/stream-events.ts:91

needsApproval?

optional needsApproval?: boolean;

Defined in: agent/stream-events.ts:92

StreamRunOptions

Defined in: agent/stream-run.ts:46

Properties

messageId

messageId: string;

Defined in: agent/stream-run.ts:48

Id of the assistant message being streamed (opaque; carried in events).

baseRequest

baseRequest: StreamChatRequest;

Defined in: agent/stream-run.ts:50

Turn-1 request; the loop clones its messages and enriches them per turn.

transportCall

transportCall: (request) => Promise<
  | string
| AsyncIterable<StreamChatEvent, any, any>>;

Defined in: agent/stream-run.ts:57

Calls the transport with the (possibly enriched) request. Returns the structured stream, or a plain string for a non-streaming provider. Mirrors getTransport().chat(provider, request, auth, ctx) with provider/auth/ctx closed over by the adapter.

Parameters

Parameter	Type
`request`	`StreamChatRequest`

Returns

Promise< | string | AsyncIterable<StreamChatEvent, any, any>>

toolLookup

toolLookup: (name) => StreamToolHandler | undefined;

Defined in: agent/stream-run.ts:59

Resolves a tool’s handler by name (mirrors AparteConfig.getToolHandler).

Parameters

Parameter	Type
`name`	`string`

Returns

StreamToolHandler | undefined

toolConfigLookup?

optional toolConfigLookup?: (name) => StreamToolConfig | undefined;

Defined in: agent/stream-run.ts:61

Resolves a tool’s loop config by name (maxTurns / needsApproval).

Parameters

Parameter	Type
`name`	`string`

Returns

StreamToolConfig | undefined

approvalResolver?

optional approvalResolver?: StreamApprovalResolver;

Defined in: agent/stream-run.ts:63

HITL approval resolver for needsApproval tools (default: never called).

emitter

emitter: StreamRunEmitter;

Defined in: agent/stream-run.ts:65

Synchronous, ordered event sink consumed by the adapter.

signal

signal: AbortSignal;

Defined in: agent/stream-run.ts:67

Single abort signal composing _isAborted + the stream controller.

maxTurns?

optional maxTurns?: number;

Defined in: agent/stream-run.ts:69

Global turn cap.

Default

toolTimeoutMs?

optional toolTimeoutMs?: number;

Defined in: agent/stream-run.ts:71

Per-tool-call handler timeout in ms.

Default

idGen?

optional idGen?: (prefix) => string;

Defined in: agent/stream-run.ts:78

Generates artifact segment ids (prefix is e.g. 'artifact-raw'). The default is a deterministic per-run counter; the adapter injects a crypto-based one to match _streamLoop’s artifact-*-<uuid>. (Tool ids still flow from the stream; only artifacts need generated ids.)

Parameters

Parameter	Type
`prefix`	`string`

Returns

string

CompactionMessage

Defined in: conversation/compactor.ts:27

conversation/compactor.ts — adaptive budgeting + context-window assembly.

Conversation history budgeting and sliding-window assembly — framework-free and tokenizer-free (char-count heuristic).

Pattern (cf. Claude Code /context, OpenAI Agents SDK TrimmingSession): Budget = CONTEXT_WINDOW − systemPrompt − tools − reservedThinking − reservedGeneration − autocompactBuffer − safetyMargin

The history budget is then split into:

summary (global summary, LLM-generated, ~10%)
ragHist (older turns retrieved by cosine similarity, ~25%)
window (verbatim sliding window, the rest)

Drop priority on overflow:

summary (async-regenerable)
ragHist (retrievable on the next turn)
window oldest turns X. NEVER dropped: currentUser + lastAssistant (absolute working memory)

Browser-portable: zero deps, just an estimateTokens heuristic.

Properties

role

role: "tool" | "system" | "assistant" | "user";

Defined in: conversation/compactor.ts:28

content

content: string;

Defined in: conversation/compactor.ts:29

RetrievedTurn

Defined in: conversation/compactor.ts:32

Properties

role

role: "assistant" | "user";

Defined in: conversation/compactor.ts:33

content

content: string;

Defined in: conversation/compactor.ts:34

score?

optional score?: number;

Defined in: conversation/compactor.ts:35

CompactionConfig

Defined in: conversation/compactor.ts:38

Properties

contextWindow

contextWindow: number;

Defined in: conversation/compactor.ts:40

Total context window of the active model, in tokens.

reservedThinking

reservedThinking: number;

Defined in: conversation/compactor.ts:42

Reserved budget for the model’s thinking/reasoning block, in tokens.

reservedGeneration

reservedGeneration: number;

Defined in: conversation/compactor.ts:44

Reserved budget for the assistant response (max_new_tokens cap).

autocompactBufferPct

autocompactBufferPct: number;

Defined in: conversation/compactor.ts:46

Fraction of context_window kept as autocompact buffer (0..1).

safetyMargin

safetyMargin: number;

Defined in: conversation/compactor.ts:48

Hard safety margin in tokens.

minHistoryBudget

minHistoryBudget: number;

Defined in: conversation/compactor.ts:50

Floor for history budget — never compact below this.

summaryRatio

summaryRatio: number;

Defined in: conversation/compactor.ts:52

Ratio of history budget allocated to the summary block.

summaryMaxTokens

summaryMaxTokens: number;

Defined in: conversation/compactor.ts:54

Hard cap for summary tokens.

ragHistRatio

ragHistRatio: number;

Defined in: conversation/compactor.ts:56

Ratio of history budget allocated to the RAG-retrieved old turns.

ragHistMaxTokens

ragHistMaxTokens: number;

Defined in: conversation/compactor.ts:58

Hard cap for ragHist tokens.

triggerSummaryThresholdPct

triggerSummaryThresholdPct: number;

Defined in: conversation/compactor.ts:60

Trigger summarization once history usage reaches this % of the budget.

summarizeEveryNTurns

summarizeEveryNTurns: number;

Defined in: conversation/compactor.ts:62

Re-run summarization every N user turns.

summaryLabel

summaryLabel: string;

Defined in: conversation/compactor.ts:65

Header prepended to the summary block injected into the model context. English by default — override to localise (the compactor ships no locale system).

ragIntroLabel

ragIntroLabel: string;

Defined in: conversation/compactor.ts:67

Header prepended to the RAG-retrieved old turns injected into the context.

BudgetBreakdown

Defined in: conversation/compactor.ts:70

Extended by

FullBreakdown

Properties

contextWindow

contextWindow: number;

Defined in: conversation/compactor.ts:71

systemPrompt

systemPrompt: number;

Defined in: conversation/compactor.ts:72

tools

tools: number;

Defined in: conversation/compactor.ts:73

reservedThinking

reservedThinking: number;

Defined in: conversation/compactor.ts:74

reservedGeneration

reservedGeneration: number;

Defined in: conversation/compactor.ts:75

autocompactBuffer

autocompactBuffer: number;

Defined in: conversation/compactor.ts:76

safetyMargin

safetyMargin: number;

Defined in: conversation/compactor.ts:77

historyAvailable

historyAvailable: number;

Defined in: conversation/compactor.ts:78

BudgetResult

Defined in: conversation/compactor.ts:81

Properties

historyBudget

historyBudget: number;

Defined in: conversation/compactor.ts:82

breakdown

breakdown: BudgetBreakdown;

Defined in: conversation/compactor.ts:83

config

config: CompactionConfig;

Defined in: conversation/compactor.ts:84

SplitBudget

Defined in: conversation/compactor.ts:87

Properties

summary

summary: number;

Defined in: conversation/compactor.ts:88

ragHist

ragHist: number;

Defined in: conversation/compactor.ts:89

window

window: number;

Defined in: conversation/compactor.ts:90

UsageBreakdown

Defined in: conversation/compactor.ts:93

Properties

system

system: number;

Defined in: conversation/compactor.ts:94

summary

summary: number;

Defined in: conversation/compactor.ts:95

ragHist

ragHist: number;

Defined in: conversation/compactor.ts:96

window

window: number;

Defined in: conversation/compactor.ts:97

DroppedBreakdown

Defined in: conversation/compactor.ts:100

Properties

ragHits

ragHits: number;

Defined in: conversation/compactor.ts:101

oldTurns

oldTurns: number;

Defined in: conversation/compactor.ts:102

summary

summary: boolean;

Defined in: conversation/compactor.ts:103

FullBreakdown

Defined in: conversation/compactor.ts:106

Extends

BudgetBreakdown

Properties

contextWindow

contextWindow: number;

Defined in: conversation/compactor.ts:71

Inherited from

BudgetBreakdown.contextWindow

systemPrompt

systemPrompt: number;

Defined in: conversation/compactor.ts:72

Inherited from

BudgetBreakdown.systemPrompt

tools

tools: number;

Defined in: conversation/compactor.ts:73

Inherited from

BudgetBreakdown.tools

reservedThinking

reservedThinking: number;

Defined in: conversation/compactor.ts:74

Inherited from

BudgetBreakdown.reservedThinking

reservedGeneration

reservedGeneration: number;

Defined in: conversation/compactor.ts:75

Inherited from

BudgetBreakdown.reservedGeneration

autocompactBuffer

autocompactBuffer: number;

Defined in: conversation/compactor.ts:76

Inherited from

BudgetBreakdown.autocompactBuffer

safetyMargin

safetyMargin: number;

Defined in: conversation/compactor.ts:77

Inherited from

BudgetBreakdown.safetyMargin

historyAvailable

historyAvailable: number;

Defined in: conversation/compactor.ts:78

Inherited from

BudgetBreakdown.historyAvailable

historyAllocated

historyAllocated: SplitBudget;

Defined in: conversation/compactor.ts:107

historyUsed

historyUsed: UsageBreakdown;

Defined in: conversation/compactor.ts:108

totalUsed

totalUsed: number;

Defined in: conversation/compactor.ts:109

free

free: number;

Defined in: conversation/compactor.ts:111

Free tokens left in the context window after all reservations + actual use.

dropped

dropped: DroppedBreakdown;

Defined in: conversation/compactor.ts:112

CompactionInput

Defined in: conversation/compactor.ts:115

Properties

messages

messages: CompactionMessage[];

Defined in: conversation/compactor.ts:116

systemPrompt

systemPrompt: string;

Defined in: conversation/compactor.ts:117

toolsArray?

optional toolsArray?: unknown;

Defined in: conversation/compactor.ts:119

Tools array passed to apply_chat_template (or null/undefined when no tools).

summary?

optional summary?: string;

Defined in: conversation/compactor.ts:121

Running summary text (regenerable).

retrievedTurns?

optional retrievedTurns?: RetrievedTurn[];

Defined in: conversation/compactor.ts:123

RAG-retrieved old turns (older than the sliding window).

config?

optional config?: Partial<CompactionConfig>;

Defined in: conversation/compactor.ts:125

Partial override of the default config.

CompactionResult

Defined in: conversation/compactor.ts:128

Properties

compactedMessages

compactedMessages: CompactionMessage[];

Defined in: conversation/compactor.ts:129

breakdown

breakdown: FullBreakdown;

Defined in: conversation/compactor.ts:130

Type Aliases

XmlArtifactState

type XmlArtifactState = "normal" | "scanning" | "in-artifact";

Defined in: agent/parsers/artifact-xml-state-machine.ts:21

Where the streaming parser is between artifacts.

XmlArtifactEvent

type XmlArtifactEvent =
  | {
  type: "chat-text";
  text: string;
  reduced?: boolean;
}
  | {
  type: "artifact-open";
  id: string;
  mimeType: string;
  kind: string;
  title: string;
}
  | {
  type: "artifact-chunk";
  id: string;
  content: string;
}
  | {
  type: "artifact-close";
  id: string;
  content: string;
  inline: boolean;
};

Defined in: agent/parsers/artifact-xml-state-machine.ts:30

DOM-free micro-events the machine emits; the adapter renders them.

StreamChatEvent

type StreamChatEvent =
  | {
  type: "text";
  delta: string;
}
  | {
  type: "thinking";
  delta: string;
}
  | {
  type: "tool_use";
  id: string;
  name: string;
  input: unknown;
}
  | {
  type: "error";
  message: string;
}
  | {
  type: "done";
  usage?: StreamUsage;
};

Defined in: agent/stream-events.ts:53

A structured stream event from the transport (mirrors AparteStreamEvent). The tool_use variant spreads StreamToolCall exactly like core’s does.

StreamToolHandler

type StreamToolHandler = (call, signal) => Promise<{
  content: string;
}>;

Defined in: agent/stream-events.ts:84

A tool handler (mirrors the resolved AparteToolHandler).

Parameters

Parameter	Type
`call`	`StreamToolCall`
`signal`	`AbortSignal`

Returns

Promise<{ content: string; }>

StreamApprovalResolver

type StreamApprovalResolver = (toolCallId, signal) => Promise<{
  approved: boolean;
  payload?: unknown;
}>;

Defined in: agent/stream-events.ts:99

Resolves a human-in-the-loop approval (mirrors core’s AparteToolApprovalResolver). Injected so the loop stays headless.

Parameters

Parameter	Type
`toolCallId`	`string`
`signal`	`AbortSignal`

Returns

Promise<{ approved: boolean; payload?: unknown; }>

StreamRunEvent

type StreamRunEvent =
  | {
  type: "run-start";
}
  | {
  type: "turn-start";
}
  | {
  type: "text-delta";
  delta: string;
  reduced?: boolean;
}
  | {
  type: "text-flush";
}
  | {
  type: "thinking-delta";
  delta: string;
}
  | {
  type: "artifact-open";
  id: string;
  mimeType: string;
  kind: string;
  title: string;
}
  | {
  type: "artifact-chunk";
  id: string;
  content: string;
}
  | {
  type: "artifact-close";
  id: string;
  content: string;
  inline: boolean;
}
  | {
  type: "artifact-ready";
  id: string;
  mimeType: string;
  kind: string;
  title: string;
  content: string;
}
  | {
  type: "tool-start";
  toolCallId: string;
  name: string;
  input: unknown;
}
  | {
  type: "tool-awaiting-approval";
  toolCallId: string;
  name: string;
  input: unknown;
}
  | {
  type: "tool-approved";
  toolCallId: string;
}
  | {
  type: "tool-rejected";
  toolCallId: string;
  reason: string;
}
  | {
  type: "tool-resolved";
  toolCallId: string;
  result: string;
}
  | {
  type: "tool-aborted";
  toolCallId: string;
}
  | {
  type: "turn-limit-exceeded";
  scope: "global" | "tool";
  limit: number;
  toolCallId?: string;
}
  | {
  type: "phase-advance";
  index: number;
}
  | {
  type: "run-aborted";
}
  | {
  type: "run-done";
  usage?: StreamUsage;
};

Defined in: agent/stream-events.ts:132

High-level, DOM-free events isomorphic to _streamLoop’s targetElement.* call sequence. Emitted synchronously and in order (see StreamRunEmitter) so the adapter reproduces the exact streaming update order.

Mapping to _streamLoop (aparte-client.ts) for the adapter:

run-start → updateMessage(status:‘streaming’) once at loop entry (the leading write before turn 1)
turn-start → reset the per-turn parser / thinking / streaming-segment state (no DOM); one per turn
text-delta → parser-driven addSegment/updateSegment, else typeName/updateLastMessage
text-flush → textParser.finalize() then addSegment/updateSegment the finalized segments; one per turn, after the inner SSE loop ends (surfaced by the spike — a turn-boundary flush)
thinking-delta → addSegment(‘thinking’) then updateSegment(content); first text-delta after thinking collapses it (updateSegment collapsed:true)
tool-start → renderer lookup + per-tool-name CSS inject into document.head + addSegment
tool-awaiting-approval → updateSegment(‘awaiting-approval’) + dispatch aparte-tool-approval-request
tool-approved → updateSegment(‘pending’)
tool-rejected → updateSegment(‘rejected’, result)
tool-resolved → updateSegment(‘resolved’, result)
tool-aborted → updateSegment(‘aborted’) (no-handler path, timeout/abort path, or per-tool maxTurns path)
turn-limit-exceeded scope:‘global’ → addSegment(error ‘MAX_TURNS_EXCEEDED’); scope:‘tool’ → updateSegment(‘aborted’)
phase-advance → addSegment({type:‘pipeline-waiting’}); the loop has already pushed the phase’s reply into history and bumped the phase index
run-aborted → dispatch aparte-message-aborted (from the inner-loop abort check or the outer turn-boundary abort check)
run-done → updateMessage(status:‘completed’) always + setUsage if usage

StreamRunEmitter

type StreamRunEmitter = (event) => void;

Defined in: agent/stream-events.ts:174

Synchronous event sink — mirrors AGUIEmitter. Synchronous by contract: the loop must never yield between emitting an event and its ordered successor, or the adapter’s streaming updates would interleave out of order.

Parameters

Parameter	Type
`event`	`StreamRunEvent`

Returns

void

Variables

DEFAULT_COMPACTION_CONFIG

const DEFAULT_COMPACTION_CONFIG: CompactionConfig;

Defined in: conversation/compactor.ts:135

Functions

deriveArtifactKind()

function deriveArtifactKind(mimeType, fallback?): string;

Defined in: agent/parsers/artifact-xml-state-machine.ts:53

Map an artifact mimeType to a renderer kind. Byte-identical copy of core’s canonical deriveArtifactKind (parsers/aparte-stream-parser.ts) — the duplicate stays because @aparte/core is an OPTIONAL peer of the engine, so no runtime import is possible. Kept in sync mechanically by __tests__/derive-artifact-kind-parity.test.ts.

Parameters

Parameter	Type	Default value
`mimeType`	`string`	`undefined`
`fallback`	`string`	`'unknown'`

Returns

string

runStreamAgent()

function runStreamAgent(opts): Promise<StreamUsage | undefined>;

Defined in: agent/stream-run.ts:88

Run the structured-stream agent loop. Resolves the last turn’s usage (the done{usage} last-write-wins, mirroring _streamLoop’s return), or undefined. Throws on a stream error event or a non-abort tool failure — the caller (adapter) routes that to its lifecycle-error handler, exactly as _handleSend/_handleRetry/_handleEdit catch _streamLoop.

Parameters

Parameter	Type
`opts`	`StreamRunOptions`

Returns

Promise<StreamUsage | undefined>

estimateTokens()

function estimateTokens(text): number;

Defined in: conversation/compactor.ts:164

Token heuristic (FR ~3.5 chars/tok, EN ~4 chars/tok). Accurate to ±10% — enough for budgeting, and it avoids tokenizer.encode(), which costs ~5ms per message × N (too slow to run on every turn).

Parameters

Parameter	Type
`text`	`string` \| `null` \| `undefined`

Returns

number

estimateTokensJson()

function estimateTokensJson(obj): number;

Defined in: conversation/compactor.ts:172

Estimate tokens for a JSON-serializable structure (e.g. tools array).

Parameters

Parameter	Type
`obj`	`unknown`

Returns

number

computeHistoryBudget()

function computeHistoryBudget(input): BudgetResult;

Defined in: conversation/compactor.ts:186

Compute the available history budget after subtracting fixed costs.

Parameters

Parameter	Type
`input`	{ `systemPrompt`: `string`; `toolsArray?`: `unknown`; `config?`: `Partial`<`CompactionConfig`>; }
`input.systemPrompt`	`string`
`input.toolsArray?`	`unknown`
`input.config?`	`Partial`<`CompactionConfig`>

Returns

BudgetResult

splitHistoryBudget()

function splitHistoryBudget(historyBudget, cfg?): SplitBudget;

Defined in: conversation/compactor.ts:222

Split history budget into summary / ragHist / window slots.

Parameters

Parameter	Type	Default value
`historyBudget`	`number`	`undefined`
`cfg`	`CompactionConfig`	`DEFAULT_COMPACTION_CONFIG`

Returns

SplitBudget

assembleCompacted()

function assembleCompacted(params): AssembleResult;

Defined in: conversation/compactor.ts:262

Assemble compacted message list given a budget and conversation state.

Output order: [system?] → [summary system msg?] → [ragHist system msg?] → window verbatim

Always keeps the last 2 non-system messages verbatim (working memory), regardless of windowBudget — these are the floor that can never be dropped.

Parameters

Parameter	Type
`params`	`AssembleParams`

Returns

AssembleResult

compactConversation()

function compactConversation(input): CompactionResult;

Defined in: conversation/compactor.ts:369

Compute budget + assemble in one call. The primary entry point for consumers (a browser request interceptor, mobile, Node tests).

Parameters

Parameter	Type
`input`	`CompactionInput`

Returns

CompactionResult