API Reference
Context Types Type definitions for Context, ItemLog, Item variants, and content parts in Noetic.
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 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 : 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 idstringUnique execution identifier stepCountnumberNumber of steps executed so far tokensTokenUsageAccumulated token usage elapsednumberElapsed time in milliseconds costnumberAccumulated cost in USD contextTContextTyped context object. Access layer data via ctx.context['layerId'].prop. Defaults to ContextData when no ContextConfig is provided. stateTStateMutable user state parentContext | nullParent context (for spawned agents) depthnumberNesting depth (0 for root) spanSpanObservability span threadIdstringThread identifier for context scoping resourceIdstringResource identifier for context scoping (optional) harnessAgentHarnessReference to the owning agent harness. Access params via ctx.harness.config.params. fsFsAdapterFilesystem adapter delegated from ctx.harness.fs. Use for all filesystem operations inside steps and tools. itemLogItemLogConversation history lastStepMetaStepMeta | nullMetadata from the last executed step lastLayerUsageLastLayerUsage | undefinedPer-context-layer breakdown of the context window from the most recent callModel. Undefined until the first LLM call completes. completedbooleanWhether complete() has been called completionValueunknownValue passed to complete() abortedbooleanWhether abort() has been called abortReasonstringReason passed to abort() (optional)
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 | nullNon-blocking receive checkpoint() => Promise<void>Persist current state complete<T>(value) => voidSignal completion with a value abort(reason?) => voidSignal 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
An append-only log of conversation items.
interface ItemLog { readonly items : ReadonlyArray < Item >; append ( item : Item ) : void ; } Field Type Description itemsReadonlyArray<Item>All items in the log append(item: Item) => voidAppend a new item
The Item type is a discriminated union over the type field:
type Item = | MessageItem | FunctionCallItem | FunctionCallOutputItem | ReasoningItem | ExtensionItem ; All items share this base:
Field Type Description idstringUnique item identifier status'in_progress' | 'completed' | 'incomplete' | 'failed'Item status
Field Type Description type'message'Discriminant role'user' | 'assistant' | 'system' | 'developer'Message author contentContentPart[]Message content parts
Field Type Description type'function_call'Discriminant callIdstringUnique call identifier namestringFunction name argumentsstringJSON-encoded arguments
Field Type Description type'function_call_output'Discriminant callIdstringMatching call identifier outputstringJSON-encoded output
Field Type Description type'reasoning'Discriminant contentContentPart[]Reasoning content summaryContentPart[]Summary of reasoning (optional) encryptedContentstringEncrypted reasoning content (optional)
Field Type Description type`${string}:${string}`Namespaced type using prefix:name convention (e.g., openrouter:web_search, noetic:analytics) dataRecord<string, unknown>Arbitrary structured data
See Items & Events for the complete reference including built-in extended items, streaming events, and the adapter flow.
type ContentPart = | { type : 'output_text' ; text : string } | { type : 'input_text' ; text : string } | { type : 'refusal' ; refusal : string }; Variant Fields Description output_texttext: stringText generated by the model input_texttext: stringText from the user or system refusalrefusal: stringModel refusal message
Field Type Description inputnumberInput tokens consumed outputnumberOutput tokens generated totalnumberTotal tokens cachednumberPrompt tokens served from the provider's cache, accumulated over the execution (optional)
Field Type Description toolCallsFunctionCallItem[]Tool calls made in this step (optional) usageRoundUsage — { 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) costnumberStep cost in USD (optional) responseItemsReadonlyArray<Item>Items produced by this step (optional)
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 layerIdstringThe contributing context layer's id tokenCountnumberSelf-reported token count from the layer's recall() output itemsReadonlyArray<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 cachechangedbooleanWhether the layer's fresh output differed from its pin, and so was superseded churnRatenumberShare of watched assemblies in which this layer's output changed, 0–1 rebillTokensnumberTokens this layer's changes would have re-billed had it not been pinned
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 idstringIdentifies the run of assemblies sharing one set of pins agenumberAssemblies served by this epoch, including the one just made anchorTokensnumberTokens in the anchor band — the cache-stable prefix liveTokensnumberTokens in the live band, rendered after history deltaTokensnumberTokens spent superseding stale anchors reanchorReasonReanchorReasonSet only on an assembly that re-anchored
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 executionIdstringThe owning Context.id modelIdstringModel id from the step that triggered the snapshot layersReadonlyArray<LayerUsageEntry>Per-context-layer contributions, sorted by layerId systemPromptTokensnumberEstimated tokens from step.instructions toolsTokensnumberEstimated tokens from the tool definitions sent to the model historyTokensnumberEstimated tokens for itemLog items not owned by a layer totalUsedTokensnumberSum of all four buckets epochEpochUsage | undefinedAnchoring 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.