Type definitions for Context, ItemLog, Item variants, and content parts in Noetic.

Context

The execution context threaded through every step.

interface Context<TContext = ContextData, TState = unknown> {
  readonly id: string;
  readonly stepCount: number;
  readonly tokens: TokenUsage;
  readonly elapsed: number;
  readonly cost: number;
  readonly billedCost: number;
  readonly heldCost: number;
  readonly context: TContext;
  state: TState;
  readonly parent: Context | null;
  readonly depth: number;
  readonly span: Span;
  readonly threadId: string;
  readonly resourceId?: string;
  readonly harness: AgentHarness;
  readonly fs: FsAdapter;
  readonly itemLog: ItemLog;
  readonly lastStepMeta: StepMeta | null;
  readonly lastLayerUsage?: LastLayerUsage;
  recv<T>(channel: Channel<T>, opts?: { timeout?: number }): Promise<T>;
  send<T>(channel: Channel<T>, value: NoInfer<T>): Promise<void>;
  tryRecv<T>(channel: Channel<T>): T | null;
  checkpoint(): Promise<void>;
  complete<T>(value: T): void;
  readonly completed: boolean;
  readonly completionValue: unknown;
  readonly aborted: boolean;
  readonly abortReason?: string;
  abort(reason?: string): void;
}

Field	Type	Description
`id`	`string`	Unique execution identifier
`stepCount`	`number`	Number of steps executed so far
`tokens`	`TokenUsage`	Accumulated token usage
`elapsed`	`number`	Elapsed time in milliseconds
`cost`	`number`	Accumulated cost in USD of the work run on this context, including spend restored from a checkpoint
`billedCost`	`number`	USD this context's calls actually paid during this attempt. Replayed steps and rounds add nothing and a restored context starts at `0`, so `cost - billedCost` is what replay saved
`heldCost`	`number`	USD held for this execution's paid calls that were cut off and have no settled bill yet, each at its ceiling until reconciled. A bound, never part of `cost` or `billedCost`; nonzero only on a root context. See Paid Calls
`context`	`TContext`	Typed context object. Access layer data via `ctx.context['layerId'].prop`. Defaults to `ContextData` when no `ContextConfig` is provided.
`state`	`TState`	Mutable user state
`parent`	`Context \| null`	Parent context (for spawned agents)
`depth`	`number`	Nesting depth (0 for root)
`span`	`Span`	Observability span
`threadId`	`string`	Thread identifier for context scoping
`resourceId`	`string`	Resource identifier for context scoping (optional)
`harness`	`AgentHarness`	Reference to the owning agent harness. Access params via `ctx.harness.config.params`.
`fs`	`FsAdapter`	Filesystem adapter delegated from `ctx.harness.fs`. Use for all filesystem operations inside steps and tools.
`itemLog`	`ItemLog`	Conversation history
`lastStepMeta`	`StepMeta \| null`	Metadata from the last executed step
`lastLayerUsage`	`LastLayerUsage \| undefined`	Per-context-layer breakdown of the context window from the most recent `callModel`. Undefined until the first LLM call completes.
`completed`	`boolean`	Whether `complete()` has been called
`completionValue`	`unknown`	Value passed to `complete()`
`aborted`	`boolean`	Whether `abort()` has been called
`abortReason`	`string`	Reason passed to `abort()` (optional)

Context Methods

Method	Signature	Description
`recv`	`<T>(channel, opts?) => Promise<T>`	Receive from a channel (blocking)
`send`	`<T>(channel, value) => Promise<void>`	Send to a channel. Parks when a queue channel is at capacity (back-pressure: `channel_timeout` after 30s, `cancelled` on abort)
`tryRecv`	`<T>(channel) => T \| null`	Non-blocking receive
`checkpoint`	`() => Promise<void>`	Persist current state
`complete`	`<T>(value) => void`	Signal completion with a value
`abort`	`(reason?) => void`	Signal abort. Cascades to every live `inParallel` path and `spawn` child of this context (never to the parent); first call wins. Does not run context-layer teardown — see `harness.cancel`

ItemLog

An append-only log of conversation items.

interface ItemLog {
  readonly items: ReadonlyArray<Item>;
  append(item: Item): void;
}

Field	Type	Description
`items`	`ReadonlyArray<Item>`	All items in the log
`append`	`(item: Item) => void`	Append a new item

Item

The Item type is a discriminated union over the type field:

type Item =
  | MessageItem
  | FunctionCallItem
  | FunctionCallOutputItem
  | ReasoningItem
  | ExtensionItem;

ItemBase

All items share this base:

Field	Type	Description
`id`	`string`	Unique item identifier
`status`	`'in_progress' \| 'completed' \| 'incomplete' \| 'failed'`	Item status

MessageItem

Field	Type	Description
`type`	`'message'`	Discriminant
`role`	`'user' \| 'assistant' \| 'system' \| 'developer'`	Message author
`content`	`ContentPart[]`	Message content parts

FunctionCallItem

Field	Type	Description
`type`	`'function_call'`	Discriminant
`callId`	`string`	Unique call identifier
`name`	`string`	Function name
`arguments`	`string`	JSON-encoded arguments

FunctionCallOutputItem

Field	Type	Description
`type`	`'function_call_output'`	Discriminant
`callId`	`string`	Matching call identifier
`output`	`string`	JSON-encoded output

ReasoningItem

Field	Type	Description
`type`	`'reasoning'`	Discriminant
`content`	`ContentPart[]`	Reasoning content
`summary`	`ContentPart[]`	Summary of reasoning (optional)
`encryptedContent`	`string`	Encrypted reasoning content (optional)

ExtensionItem

Field	Type	Description
`type`	`${string}:${string}`	Namespaced type using `prefix:name` convention (e.g., `openrouter:web_search`, `noetic:analytics`)
`data`	`Record<string, unknown>`	Arbitrary structured data

See Items & Events for the complete reference including built-in extended items, streaming events, and the adapter flow.

ContentPart

type ContentPart =
  | { type: 'output_text'; text: string }
  | { type: 'input_text'; text: string }
  | { type: 'refusal'; refusal: string };

Variant	Fields	Description
`output_text`	`text: string`	Text generated by the model
`input_text`	`text: string`	Text from the user or system
`refusal`	`refusal: string`	Model refusal message

TokenUsage

Field	Type	Description
`input`	`number`	Input tokens consumed
`output`	`number`	Output tokens generated
`total`	`number`	Total tokens
`cached`	`number`	Prompt tokens served from the provider's cache, accumulated over the execution (optional)

StepMeta

Field	Type	Description
`toolCalls`	`FunctionCallItem[]`	Tool calls made in this step (optional)
`usage`	`RoundUsage` — `{ inputTokens, outputTokens, cachedTokens?, cacheWriteTokens? }`	Token usage for the step. The two cache fields are `undefined` when the provider reports no cache figures, which is not the same as a reported zero (optional)
`cost`	`number`	Step cost in USD (optional)
`billedCost`	`number`	USD the step's call actually paid — see `LLMResponse.billedCost` (optional)
`responseItems`	`ReadonlyArray<Item>`	Items produced by this step (optional)
`decision`	`DecisionMeta` — `{ modelId, source: 'native' \| 'estimated', refused: readonly string[] }`	Set by `decide` steps: the model that answered, which model path it took, and the ids of refused questions (optional)

LayerUsageEntry

interface LayerUsageEntry {
  readonly layerId: string;
  readonly tokenCount: number;
  readonly items: ReadonlyArray<Item>;
  readonly placement: 'anchor' | 'live';
  readonly served: 'fresh' | 'pinned';
  readonly changed: boolean;
  readonly churnRate: number;
  readonly rebillTokens: number;
}

Field	Type	Description
`layerId`	`string`	The contributing context layer's id
`tokenCount`	`number`	Self-reported token count from the layer's `recall()` output
`items`	`ReadonlyArray<Item>`	Items this layer contributed to the context view for the last LLM call
`placement`	`'anchor' \| 'live'`	The band the layer rendered into. Resolved, so an `'auto'` layer reports where it landed
`served`	`'fresh' \| 'pinned'`	`'pinned'` when the items are a replay of an earlier render, held for the prompt cache
`changed`	`boolean`	Whether the layer's fresh output differed from its pin, and so was superseded
`churnRate`	`number`	Share of watched assemblies in which this layer's output changed, 0–1
`rebillTokens`	`number`	Tokens this layer's changes would have re-billed had it not been pinned

EpochUsage

Prompt-cache anchoring state behind the most recent assembly. See Prompt Cache Anchoring.

interface EpochUsage {
  readonly id: string;
  readonly age: number;
  readonly anchorTokens: number;
  readonly liveTokens: number;
  readonly deltaTokens: number;
  readonly reanchorReason?: ReanchorReason;
}

Field	Type	Description
`id`	`string`	Identifies the run of assemblies sharing one set of pins
`age`	`number`	Assemblies served by this epoch, including the one just made
`anchorTokens`	`number`	Tokens in the anchor band — the cache-stable prefix
`liveTokens`	`number`	Tokens in the live band, rendered after history
`deltaTokens`	`number`	Tokens spent superseding stale anchors
`reanchorReason`	`ReanchorReason`	Set only on an assembly that re-anchored

LastLayerUsage

interface LastLayerUsage {
  readonly executionId: string;
  readonly modelId: string;
  readonly layers: ReadonlyArray<LayerUsageEntry>;
  readonly systemPromptTokens: number;
  readonly toolsTokens: number;
  readonly historyTokens: number;
  readonly totalUsedTokens: number;
  readonly epoch?: EpochUsage;
}

Field	Type	Description
`executionId`	`string`	The owning `Context.id`
`modelId`	`string`	Model id from the step that triggered the snapshot
`layers`	`ReadonlyArray<LayerUsageEntry>`	Per-context-layer contributions, sorted by `layerId`
`systemPromptTokens`	`number`	Estimated tokens from `step.instructions`
`toolsTokens`	`number`	Estimated tokens from the tool definitions sent to the model
`historyTokens`	`number`	Estimated tokens for `itemLog` items not owned by a layer
`totalUsedTokens`	`number`	Sum of all four buckets
`epoch`	`EpochUsage \| undefined`	Anchoring state behind this assembly. Absent when `contextCache.enabled` is `false`

LastLayerUsage is captured by the runtime after each successful callModel and surfaced on Context.lastLayerUsage and HarnessResponse.lastLayerUsage. Use it for context-window introspection (e.g., the CLI /context command). The snapshot is overwritten on the next call; export to your observability span if you need historical retention.

Context Types