@agentskit/observability — Interfaces

#Interface: AdvancedCostGuard

Defined in: observability/src/cost-guard-advanced.ts:51

Production-grade cost guard. Extends the multi-tenant guard with modes (warn / reject / kill), rolling window caps, threshold + forecast alerts, and pluggable sinks. Closes #787–#789.

#Extends

Observer

#Properties

#costUsd

costUsd: (tenant) => number

Defined in: observability/src/cost-guard-advanced.ts:53

#Parameters

#Returns

number

#enable

enable: (tenant) => void

Defined in: observability/src/cost-guard-advanced.ts:64

Re-enable a tenant disabled by kill mode. Caller must also clear the persisted flag.

#Parameters

#Returns

void

#isDisabled

isDisabled: (tenant) => boolean

Defined in: observability/src/cost-guard-advanced.ts:55

#Parameters

#Returns

boolean

#isRejected

isRejected: (tenant) => boolean

Defined in: observability/src/cost-guard-advanced.ts:62

Reject mode only: true when this tenant has tripped the overall budget or an active window's 100% cap. Window-only rejections clear when the window rolls; overall rejections last until reset. Always false in warn / kill modes.

#Parameters

tenant

string

#Returns

boolean

#name

name: string

Defined in: core/dist/chat-DSVPk7dz.d.ts:121

#Inherited from

Observer.name

#on

on: (event) => void | Promise<void>

Defined in: core/dist/chat-DSVPk7dz.d.ts:122

#Parameters

event

AgentEvent

#Returns

void | Promise<void>

#Inherited from

Observer.on

#reset

reset: (tenant?) => void

Defined in: observability/src/cost-guard-advanced.ts:65

#Parameters

tenant?

string

#Returns

void

#setTenant

setTenant: (tenant) => void

Defined in: observability/src/cost-guard-advanced.ts:52

#Parameters

tenant

string | undefined

#Returns

void

#tenants

tenants: () => string[]

Defined in: observability/src/cost-guard-advanced.ts:66

#Returns

string[]

#windowSpend

windowSpend: (tenant, window) => number | undefined

Defined in: observability/src/cost-guard-advanced.ts:54

#Parameters

tenant

string

window

string

#Returns

number | undefined

#Interface: AdvancedCostGuardOptions

Defined in: observability/src/cost-guard-advanced-types.ts:52

#Properties

#alertSinks?

optional alertSinks?: CostAlertSink[]

Defined in: observability/src/cost-guard-advanced-types.ts:78

One or more alert sinks. Fired in registration order.

#budgets

budgets: Record<string, number>

Defined in: observability/src/cost-guard-advanced-types.ts:54

Per-tenant USD budgets (overall, applied alongside windows).

#caps?

optional caps?: CostCaps

Defined in: observability/src/cost-guard-advanced-types.ts:58

Window caps applied to every tenant. Per-tenant overrides via tenantCaps.

#defaultBudgetUsd?

optional defaultBudgetUsd?: number

Defined in: observability/src/cost-guard-advanced-types.ts:56

Fallback overall budget for tenants not listed.

#disableRuntime?

optional disableRuntime?: (tenant, reason) => void | Promise<void>

Defined in: observability/src/cost-guard-advanced-types.ts:76

Called when a tenant is disabled in 'kill' mode. Must persist the disabled state (Redis flag, DB row) so the runtime stays disabled across restarts. The tenant is re-enabled only via your own out-of-band call (e.g. an admin API). Failures are isolated; kill state stays fail-closed disabled.

#Parameters

tenant

string

reason

string

#Returns

void | Promise<void>

#mode?

optional mode?: CostGuardMode

Defined in: observability/src/cost-guard-advanced-types.ts:68

Enforcement mode (default 'warn'). 'kill' requires disableRuntime.

#modelOverride?

optional modelOverride?: string

Defined in: observability/src/cost-guard-advanced-types.ts:81

#name?

optional name?: string

Defined in: observability/src/cost-guard-advanced-types.ts:85

#now?

optional now?: () => number

Defined in: observability/src/cost-guard-advanced-types.ts:84

Clock override for tests. Throws / non-finite values are isolated.

#Returns

number

#onError?

optional onError?: CostGuardErrorHandler

Defined in: observability/src/cost-guard-advanced-types.ts:80

Isolated sink for internal / callback / sink failures.

#prices?

optional prices?: Record<string, TokenPrice>

Defined in: observability/src/cost-guard-advanced-types.ts:63

#tenantCaps?

optional tenantCaps?: Record<string, CostCaps>

Defined in: observability/src/cost-guard-advanced-types.ts:60

Per-tenant override of caps. Wins over the workspace-wide caps.

#tenantOf?

optional tenantOf?: () => string | undefined

Defined in: observability/src/cost-guard-advanced-types.ts:62

Active tenant resolver (same shape as multiTenantCostGuard.tenantOf).

#Returns

string | undefined

#unknownModelPolicy?

optional unknownModelPolicy?: UnknownModelPolicy

Defined in: observability/src/cost-guard-advanced-types.ts:82

#Interface: AppendAuditInput<TPayload>

Defined in: observability/src/audit-log.ts:32

#Type Parameters

#TPayload

TPayload = unknown

#Properties

#action

action: string

Defined in: observability/src/audit-log.ts:34

#actor

actor: string

Defined in: observability/src/audit-log.ts:33

#payload

payload: TPayload

Defined in: observability/src/audit-log.ts:35

#Interface: AuditEntry<TPayload>

Defined in: observability/src/audit-log.ts:4

#Type Parameters

#TPayload

TPayload = unknown

#Properties

#action

action: string

Defined in: observability/src/audit-log.ts:9

#actor

actor: string

Defined in: observability/src/audit-log.ts:8

#payload

payload: TPayload

Defined in: observability/src/audit-log.ts:10

#prevHash

prevHash: string

Defined in: observability/src/audit-log.ts:12

Hex SHA-256 of the previous entry's canonical form. '' for seq 1.

#seq

seq: number

Defined in: observability/src/audit-log.ts:6

Monotonic sequence within a log. Starts at 1.

#signature

signature: string

Defined in: observability/src/audit-log.ts:14

Hex HMAC of the canonical form of this entry (including prevHash).

#timestamp

timestamp: string

Defined in: observability/src/audit-log.ts:7

#Interface: AuditLogOptions

Defined in: observability/src/audit-log.ts:24

#Properties

#now?

optional now?: () => Date

Defined in: observability/src/audit-log.ts:29

Clock override for tests.

#Returns

Date

#secret

secret: string

Defined in: observability/src/audit-log.ts:26

HMAC secret — rotate out-of-band.

#store

store: AuditLogStore

Defined in: observability/src/audit-log.ts:27

#Interface: AuditLogStore

Defined in: observability/src/audit-log.ts:17

#Properties

#append

append: (entry) => Promise<void>

Defined in: observability/src/audit-log.ts:18

#Parameters

entry

AuditEntry

#Returns

Promise<void>

#clear?

optional clear?: () => Promise<void>

Defined in: observability/src/audit-log.ts:21

#Returns

Promise<void>

#last

last: () => Promise<AuditEntry<unknown> | null>

Defined in: observability/src/audit-log.ts:20

#Returns

Promise<AuditEntry<unknown> | null>

#list

list: () => Promise<AuditEntry<unknown>[]>

Defined in: observability/src/audit-log.ts:19

#Returns

Promise<AuditEntry<unknown>[]>

#Interface: AuditVerifyResult

Defined in: observability/src/audit-log.ts:38

#Properties

#brokenAt?

optional brokenAt?: object

Defined in: observability/src/audit-log.ts:41

First entry where the chain broke, or null when ok.

#reason

reason: "prev-hash" | "signature"

#seq

seq: number

#entryCount

entryCount: number

Defined in: observability/src/audit-log.ts:42

#ok

ok: boolean

Defined in: observability/src/audit-log.ts:39

#Interface: AxiomSinkConfig

Defined in: observability/src/axiom.ts:9

Common batching / retry knobs for the three HTTP log sinks.

#Extends

HttpBatchOptions

#Properties

#batchSize?

optional batchSize?: number

Defined in: observability/src/http-batch-sink.ts:13

Max events per POST. Default 25. Positive integer.

#Inherited from

HttpBatchOptions.batchSize

#dataset

dataset: string

Defined in: observability/src/axiom.ts:13

Dataset name to write into.

#endpoint?

optional endpoint?: string

Defined in: observability/src/axiom.ts:15

Override the ingest endpoint (e.g. EU region: https://api.eu.axiom.co).

#fetch?

optional fetch?: {(input, init?): Promise<Response>; (input, init?): Promise<Response>; }

Defined in: observability/src/http-batch-sink.ts:26

#Call Signature

(input, init?): Promise<Response>

MDN Reference

Parameters

input

RequestInfo | URL

init?

RequestInit

Returns

Promise<Response>

#Call Signature

(input, init?): Promise<Response>

MDN Reference

Parameters

input

string | Request | URL

init?

RequestInit

Returns

Promise<Response>

#Inherited from

HttpBatchOptions.fetch

#flushIntervalMs?

optional flushIntervalMs?: number

Defined in: observability/src/http-batch-sink.ts:17

Periodic drain interval (ms). Default 2000. Finite > 0.

#Inherited from

HttpBatchOptions.flushIntervalMs

#maxQueueSize?

optional maxQueueSize?: number

Defined in: observability/src/http-batch-sink.ts:15

Hard queue cap; drop oldest when full. Default 1000. Positive integer.

#Inherited from

HttpBatchOptions.maxQueueSize

#maxRetries?

optional maxRetries?: number

Defined in: observability/src/http-batch-sink.ts:19

Retries after the initial attempt. Default 3. Integer ≥ 0.

#Inherited from

HttpBatchOptions.maxRetries

#onError?

optional onError?: (error) => void | Promise<void>

Defined in: observability/src/http-batch-sink.ts:25

Isolated error sink; throws/rejections never escape the observer.

#Parameters

error

unknown

#Returns

void | Promise<void>

#Inherited from

HttpBatchOptions.onError

#requestTimeoutMs?

optional requestTimeoutMs?: number

Defined in: observability/src/http-batch-sink.ts:23

Per-request timeout (ms). Default 10000. Positive integer.

#Inherited from

HttpBatchOptions.requestTimeoutMs

#retryBaseDelayMs?

optional retryBaseDelayMs?: number

Defined in: observability/src/http-batch-sink.ts:21

Base backoff delay (ms); doubled each attempt, capped at 30s, no jitter. Default 100.

#Inherited from

HttpBatchOptions.retryBaseDelayMs

#service?

optional service?: string

Defined in: observability/src/axiom.ts:17

Service name attached to every event.

#token

token: string

Defined in: observability/src/axiom.ts:11

Axiom API token.

#Interface: ChargebackReport

Defined in: observability/src/cost-chargeback.ts:75

#Properties

#from?

optional from?: string

Defined in: observability/src/cost-chargeback.ts:83

Window the report covers (whichever the caller passed).

#groupBy

groupBy: ChargebackGroupKey

Defined in: observability/src/cost-chargeback.ts:76

#rows

rows: ChargebackRow[]

Defined in: observability/src/cost-chargeback.ts:77

#to?

optional to?: string

Defined in: observability/src/cost-chargeback.ts:84

#totalCalls

totalCalls: number

Defined in: observability/src/cost-chargeback.ts:81

Sum of callCount across all rows.

#totalCostUsd

totalCostUsd: number

Defined in: observability/src/cost-chargeback.ts:79

Sum of costUsd across all rows.

#Interface: ChargebackReportOptions

Defined in: observability/src/cost-chargeback.ts:48

#Properties

#from?

optional from?: string

Defined in: observability/src/cost-chargeback.ts:57

Inclusive window filter (ISO 8601). Samples outside the window are dropped before grouping.

#groupBy?

optional groupBy?: ChargebackGroupKey

Defined in: observability/src/cost-chargeback.ts:50

Group key. Default 'tenant'.

#prices?

optional prices?: Record<string, TokenPrice>

Defined in: observability/src/cost-chargeback.ts:52

Optional price table override for sample cost computation.

#to?

optional to?: string

Defined in: observability/src/cost-chargeback.ts:58

#Interface: ChargebackRow

Defined in: observability/src/cost-chargeback.ts:61

#Properties

#callCount

callCount: number

Defined in: observability/src/cost-chargeback.ts:64

#completionTokens

completionTokens: number

Defined in: observability/src/cost-chargeback.ts:66

#costUsd

costUsd: number

Defined in: observability/src/cost-chargeback.ts:68

#firstAt

firstAt: string

Defined in: observability/src/cost-chargeback.ts:70

Earliest sample timestamp in the group (ISO 8601).

#group

group: string

Defined in: observability/src/cost-chargeback.ts:63

Composite group key, joined with '/' for multi-field groups.

#lastAt

lastAt: string

Defined in: observability/src/cost-chargeback.ts:72

Latest sample timestamp in the group (ISO 8601).

#promptTokens

promptTokens: number

Defined in: observability/src/cost-chargeback.ts:65

#totalTokens

totalTokens: number

Defined in: observability/src/cost-chargeback.ts:67

#Interface: ConsoleLoggerConfig

Defined in: observability/src/console-logger.ts:4

#Properties

#format?

optional format?: "human" | "json"

Defined in: observability/src/console-logger.ts:5

#Interface: ControlAuditEntry

Defined in: observability/src/prod-control.ts:75

#Properties

#action

action: "pause" | "resume" | "step" | "inject" | "snapshot" | "replay"

Defined in: observability/src/prod-control.ts:78

#actor?

optional actor?: string

Defined in: observability/src/prod-control.ts:81

Authenticated principal id, if available.

#at

at: string

Defined in: observability/src/prod-control.ts:77

ISO timestamp.

#payload?

optional payload?: Record<string, unknown>

Defined in: observability/src/prod-control.ts:83

Action-specific payload (override details, snapshot id, etc).

#runId

runId: string

Defined in: observability/src/prod-control.ts:79

#Interface: ControlSurface

Defined in: observability/src/prod-control.ts:86

#Properties

#awaitResume

awaitResume: (runId) => Promise<void>

Defined in: observability/src/prod-control.ts:107

Hook the runtime calls between iterations. Resolves immediately when the run is not paused; otherwise waits for resume / step.

#Parameters

runId

string

#Returns

Promise<void>

#consumeOverride

consumeOverride: (runId, tool) => ToolOverride | undefined

Defined in: observability/src/prod-control.ts:113

Hook the runtime calls before invoking a tool. Returns the forced result if an override is queued; otherwise undefined and the tool runs normally.

#Parameters

runId

string

tool

string

#Returns

ToolOverride | undefined

#forget

forget: (runId) => void

Defined in: observability/src/prod-control.ts:101

Release retained events, overrides, and waiters for a run.

#Parameters

runId

string

#Returns

void

#httpHandler

httpHandler: () => (req) => Promise<{ body: unknown; status: number; }>

Defined in: observability/src/prod-control.ts:118

HTTP request handler — drop into any Node http / Express / Hono route. Bearer-token gated.

#Returns

(req) => Promise<{ body: unknown; status: number; }>

#inject

inject: (runId, override, actor?) => void

Defined in: observability/src/prod-control.ts:95

Inject a tool override consumed by the next matching tool call.

#Parameters

runId

string

override

ToolOverride

actor?

string

#Returns

void

#observer

observer: Observer

Defined in: observability/src/prod-control.ts:88

Plug into createRuntime(\{ observers: [control.observer] \}).

#pause

pause: (runId, actor?) => void

Defined in: observability/src/prod-control.ts:90

Pause the loop for runId. The runtime hook awaits a resume / step.

#Parameters

runId

string

actor?

string

#Returns

void

#replay

replay: (snapshot, actor?) => void

Defined in: observability/src/prod-control.ts:99

Restore a snapshot's pending overrides + paused state. Replay events are NOT reused — replay against your own runtime.

#Parameters

snapshot

RunSnapshot

actor?

string

#Returns

void

#resume

resume: (runId, actor?) => void

Defined in: observability/src/prod-control.ts:91

#Parameters

runId

string

actor?

string

#Returns

void

#snapshot

snapshot: (runId, metadata?) => RunSnapshot

Defined in: observability/src/prod-control.ts:97

Capture a snapshot for a support ticket.

#Parameters

runId

string

metadata?

Record<string, unknown>

#Returns

RunSnapshot

#step

step: (runId, actor?) => void

Defined in: observability/src/prod-control.ts:93

Allow exactly one more iteration on a paused run.

#Parameters

runId

string

actor?

string

#Returns

void

#Interface: ControlSurfaceOptions

Defined in: observability/src/prod-control.ts:51

#Properties

#audit?

optional audit?: (entry) => void

Defined in: observability/src/prod-control.ts:60

Audit log sink — gets every control action.

#Parameters

entry

ControlAuditEntry

#Returns

void

#bearerToken?

optional bearerToken?: string

Defined in: observability/src/prod-control.ts:58

Bearer token required for HTTP access. Required when using httpHandler(). Compared with constant-time equality.

#defaultRunId?

optional defaultRunId?: string

Defined in: observability/src/prod-control.ts:70

Fallback run id when neither runIdOf nor enriched top-level runId/id fields are present on the event.

#maxRuns?

optional maxRuns?: number

Defined in: observability/src/prod-control.ts:72

Maximum number of run states retained in memory. Default 1000.

#runIdOf?

optional runIdOf?: (event) => string | undefined

Defined in: observability/src/prod-control.ts:65

Optional resolver for correlating events to a run. Checked first. Canonical event.correlation.runId is used next, then defaultRunId.

#Parameters

event

AgentEvent

#Returns

string | undefined

#snapshotBufferSize?

optional snapshotBufferSize?: number

Defined in: observability/src/prod-control.ts:53

Max events retained per run for snapshots. Default 200.

#Interface: CostAlertEvent

Defined in: observability/src/cost-guard-advanced-types.ts:26

#Properties

#at

at: string

Defined in: observability/src/cost-guard-advanced-types.ts:32

ISO 8601 timestamp.

#budgetUsd

budgetUsd: number

Defined in: observability/src/cost-guard-advanced-types.ts:36

Cap for this window (USD).

#costUsd

costUsd: number

Defined in: observability/src/cost-guard-advanced-types.ts:34

Spend so far in this window (USD).

#msUntilExceeded?

optional msUntilExceeded?: number

Defined in: observability/src/cost-guard-advanced-types.ts:45

Estimated milliseconds until the budget is exhausted at the current spend rate, when type is 'cost:forecast'.

#reason?

optional reason?: string

Defined in: observability/src/cost-guard-advanced-types.ts:47

Optional human-readable reason (mode change, etc.).

#tenant

tenant: string

Defined in: observability/src/cost-guard-advanced-types.ts:28

#threshold?

optional threshold?: number

Defined in: observability/src/cost-guard-advanced-types.ts:40

Threshold that triggered this alert (0.5, 0.8, 1.0, or undefined for forecast).

#type

type: CostAlertType

Defined in: observability/src/cost-guard-advanced-types.ts:27

#utilization

utilization: number

Defined in: observability/src/cost-guard-advanced-types.ts:38

Fraction of budget consumed (0–∞, always finite).

#window

window: string

Defined in: observability/src/cost-guard-advanced-types.ts:30

Window id ('perMinute', 'perDay', 'perMonth', custom name).

#Interface: CostCaps

Defined in: observability/src/cost-guard-advanced-types.ts:12

#Properties

#custom?

optional custom?: Record<string, CostCapWindow>

Defined in: observability/src/cost-guard-advanced-types.ts:17

Custom additional windows.

#perDay?

optional perDay?: CostCapWindow

Defined in: observability/src/cost-guard-advanced-types.ts:14

#perMinute?

optional perMinute?: CostCapWindow

Defined in: observability/src/cost-guard-advanced-types.ts:13

#perMonth?

optional perMonth?: CostCapWindow

Defined in: observability/src/cost-guard-advanced-types.ts:15

#Interface: CostCapWindow

Defined in: observability/src/cost-guard-advanced-types.ts:5

#Properties

#budgetUsd

budgetUsd: number

Defined in: observability/src/cost-guard-advanced-types.ts:9

USD ceiling per window.

#windowMs

windowMs: number

Defined in: observability/src/cost-guard-advanced-types.ts:7

Window length in milliseconds.

#Interface: CostGuardOptions

Defined in: observability/src/cost-guard.ts:50

#Properties

#budgetUsd

budgetUsd: number

Defined in: observability/src/cost-guard.ts:52

Hard budget in USD. Aborts the run when exceeded.

#controller

controller: AbortController

Defined in: observability/src/cost-guard.ts:57

AbortController to signal the runtime to stop. The runtime picks this up via RunOptions.signal (RT13).

#modelOverride?

optional modelOverride?: string

Defined in: observability/src/cost-guard.ts:80

Force a specific model id if the runtime doesn't emit one.

#name?

optional name?: string

Defined in: observability/src/cost-guard.ts:84

Observer name for tracing.

#onCost?

optional onCost?: (info) => void | Promise<void>

Defined in: observability/src/cost-guard.ts:66

Called whenever the running total changes. Useful for progress UI. Sync throws and async rejections are isolated.

#Parameters

info

budgetRemainingUsd

number

completionTokens

number

costUsd

number

promptTokens

number

#Returns

void | Promise<void>

#onError?

optional onError?: CostGuardErrorHandler

Defined in: observability/src/cost-guard.ts:78

Isolated sink for internal / callback failures. Never allowed to escape.

#onExceeded?

optional onExceeded?: (info) => void | Promise<void>

Defined in: observability/src/cost-guard.ts:76

Called when the budget is exceeded (just before / after abort bookkeeping). Sync throws and async rejections are isolated.

#Parameters

info

budgetUsd

number

costUsd

number

#Returns

void | Promise<void>

#prices?

optional prices?: Record<string, TokenPrice>

Defined in: observability/src/cost-guard.ts:61

Optional price table override. Partial — merged over DEFAULT_PRICES.

#unknownModelPolicy?

optional unknownModelPolicy?: UnknownModelPolicy

Defined in: observability/src/cost-guard.ts:82

Unknown models fail closed by default; use allow-zero only for explicitly free/local models.

#Interface: CostSample

Defined in: observability/src/cost-chargeback.ts:17

Chargeback / cost-attribution exporter. Group LLM call samples by tenant + (user | skill | tool | model | custom) and produce CSV / JSON for finance dashboards or per-tenant invoicing.

Inputs are caller-supplied CostSample[] rows. Wire your runtime to emit one sample per llm:end event (the multiTenantCostGuard already tracks the same data — feed its observer hook into a persistence layer to build the sample set).

Closes #790.

#Properties

#at

at: string

Defined in: observability/src/cost-chargeback.ts:19

ISO 8601 — when the call completed.

#completionTokens

completionTokens: number

Defined in: observability/src/cost-chargeback.ts:29

#costUsd?

optional costUsd?: number

Defined in: observability/src/cost-chargeback.ts:34

Pre-computed cost in USD. When omitted, chargebackReport will compute it from the (model, token counts, prices) triple.

#model

model: string

Defined in: observability/src/cost-chargeback.ts:27

Model id used for this call.

#promptTokens

promptTokens: number

Defined in: observability/src/cost-chargeback.ts:28

#skill?

optional skill?: string

Defined in: observability/src/cost-chargeback.ts:24

Optional skill / tool that drove the call.

#tenant

tenant: string

Defined in: observability/src/cost-chargeback.ts:20

#tool?

optional tool?: string

Defined in: observability/src/cost-chargeback.ts:25

#user?

optional user?: string

Defined in: observability/src/cost-chargeback.ts:22

Optional acting user id within the tenant.

#Interface: DatadogSinkConfig

Defined in: observability/src/datadog.ts:9

Common batching / retry knobs for the three HTTP log sinks.

#Extends

HttpBatchOptions

#Properties

#apiKey

apiKey: string

Defined in: observability/src/datadog.ts:10

#batchSize?

optional batchSize?: number

Defined in: observability/src/http-batch-sink.ts:13

Max events per POST. Default 25. Positive integer.

#Inherited from

HttpBatchOptions.batchSize

#env?

optional env?: string

Defined in: observability/src/datadog.ts:16

Environment tag (prod, staging, ...).

#fetch?

optional fetch?: {(input, init?): Promise<Response>; (input, init?): Promise<Response>; }

Defined in: observability/src/http-batch-sink.ts:26

#Call Signature

(input, init?): Promise<Response>

MDN Reference

Parameters

input

RequestInfo | URL

init?

RequestInit

Returns

Promise<Response>

#Call Signature

(input, init?): Promise<Response>

MDN Reference

Parameters

input

string | Request | URL

init?

RequestInit

Returns

Promise<Response>

#Inherited from

HttpBatchOptions.fetch

#flushIntervalMs?

optional flushIntervalMs?: number

Defined in: observability/src/http-batch-sink.ts:17

Periodic drain interval (ms). Default 2000. Finite > 0.

#Inherited from

HttpBatchOptions.flushIntervalMs

#maxQueueSize?

optional maxQueueSize?: number

Defined in: observability/src/http-batch-sink.ts:15

Hard queue cap; drop oldest when full. Default 1000. Positive integer.

#Inherited from

HttpBatchOptions.maxQueueSize

#maxRetries?

optional maxRetries?: number

Defined in: observability/src/http-batch-sink.ts:19

Retries after the initial attempt. Default 3. Integer ≥ 0.

#Inherited from

HttpBatchOptions.maxRetries

#onError?

optional onError?: (error) => void | Promise<void>

Defined in: observability/src/http-batch-sink.ts:25

Isolated error sink; throws/rejections never escape the observer.

#Parameters

error

unknown

#Returns

void | Promise<void>

#Inherited from

HttpBatchOptions.onError

#requestTimeoutMs?

optional requestTimeoutMs?: number

Defined in: observability/src/http-batch-sink.ts:23

Per-request timeout (ms). Default 10000. Positive integer.

#Inherited from

HttpBatchOptions.requestTimeoutMs

#retryBaseDelayMs?

optional retryBaseDelayMs?: number

Defined in: observability/src/http-batch-sink.ts:21

Base backoff delay (ms); doubled each attempt, capped at 30s, no jitter. Default 100.

#Inherited from

HttpBatchOptions.retryBaseDelayMs

#service?

optional service?: string

Defined in: observability/src/datadog.ts:14

Service name attached to every event.

#site?

optional site?: string

Defined in: observability/src/datadog.ts:12

Datadog site, defaults to datadoghq.com (US1). Use datadoghq.eu, us5.datadoghq.com, etc.

#Interface: DevtoolsClient

Defined in: observability/src/devtools.ts:4

#Properties

#close?

optional close?: () => void

Defined in: observability/src/devtools.ts:7

#Returns

void

#id

id: string

Defined in: observability/src/devtools.ts:5

#send

send: (event) => void

Defined in: observability/src/devtools.ts:6

#Parameters

event

DevtoolsEnvelope

#Returns

void

#Interface: DevtoolsServer

Defined in: observability/src/devtools.ts:22

#Properties

#attach

attach: (client) => () => void

Defined in: observability/src/devtools.ts:28

Attach a transport — SSE response, WS connection, in-process sink.

#Parameters

client

DevtoolsClient

#Returns

() => void

#buffer

buffer: () => readonly object[]

Defined in: observability/src/devtools.ts:32

Snapshot of retained events, newest last.

#Returns

readonly object[]

#close

close: () => void

Defined in: observability/src/devtools.ts:30

Drop all clients and clear buffer.

#Returns

void

#observer

observer: Observer

Defined in: observability/src/devtools.ts:24

Observer you can plug into createRuntime(\{ observers: [...] \}).

#publish

publish: (event) => void

Defined in: observability/src/devtools.ts:26

Push arbitrary events (tests / custom sources).

#Parameters

event

AgentEvent

#Returns

void

#Interface: DevtoolsServerOptions

Defined in: observability/src/devtools.ts:15

#Properties

#bufferSize?

optional bufferSize?: number

Defined in: observability/src/devtools.ts:17

Max events to retain in the ring buffer. Default 500.

#serverId?

optional serverId?: string

Defined in: observability/src/devtools.ts:19

Server id emitted in the hello envelope. Default: random.

#Interface: FileTraceSink

Defined in: observability/src/trace-viewer.ts:96

#Properties

#flush

flush: (options?) => Promise<{ html?: string; json: string; }>

Defined in: observability/src/trace-viewer.ts:103

Write collected spans as a JSON report and a sibling HTML viewer. Returns written paths.

#Parameters

options?

html?

boolean

traceId?

string

#Returns

Promise<{ html?: string; json: string; }>

#onSpanEnd

onSpanEnd: (span) => void

Defined in: observability/src/trace-viewer.ts:99

#Parameters

span

TraceSpan

#Returns

void

#onSpanStart

onSpanStart: (span) => void

Defined in: observability/src/trace-viewer.ts:98

Observer-compatible span callbacks. Plug into createTraceTracker.

#Parameters

span

TraceSpan

#Returns

void

#spans

spans: () => TraceSpan[]

Defined in: observability/src/trace-viewer.ts:101

Snapshot of spans recorded so far.

#Returns

TraceSpan[]

#Interface: HttpBatchOptions

Defined in: observability/src/http-batch-sink.ts:11

Common batching / retry knobs for the three HTTP log sinks.

#Extended by

#Properties

#batchSize?

optional batchSize?: number

Defined in: observability/src/http-batch-sink.ts:13

Max events per POST. Default 25. Positive integer.

#fetch?

optional fetch?: {(input, init?): Promise<Response>; (input, init?): Promise<Response>; }

Defined in: observability/src/http-batch-sink.ts:26

#Call Signature

(input, init?): Promise<Response>

MDN Reference

Parameters

input

RequestInfo | URL

init?

RequestInit

Returns

Promise<Response>

#Call Signature

(input, init?): Promise<Response>

MDN Reference

Parameters

input

string | Request | URL

init?

RequestInit

Returns

Promise<Response>

#flushIntervalMs?

optional flushIntervalMs?: number

Defined in: observability/src/http-batch-sink.ts:17

Periodic drain interval (ms). Default 2000. Finite > 0.

#maxQueueSize?

optional maxQueueSize?: number

Defined in: observability/src/http-batch-sink.ts:15

Hard queue cap; drop oldest when full. Default 1000. Positive integer.

#maxRetries?

optional maxRetries?: number

Defined in: observability/src/http-batch-sink.ts:19

Retries after the initial attempt. Default 3. Integer ≥ 0.

#onError?

optional onError?: (error) => void | Promise<void>

Defined in: observability/src/http-batch-sink.ts:25

Isolated error sink; throws/rejections never escape the observer.

#Parameters

error

unknown

#Returns

void | Promise<void>

#requestTimeoutMs?

optional requestTimeoutMs?: number

Defined in: observability/src/http-batch-sink.ts:23

Per-request timeout (ms). Default 10000. Positive integer.

#retryBaseDelayMs?

optional retryBaseDelayMs?: number

Defined in: observability/src/http-batch-sink.ts:21

Base backoff delay (ms); doubled each attempt, capped at 30s, no jitter. Default 100.

#Interface: LangSmithConfig

Defined in: observability/src/langsmith.ts:5

#Properties

#apiKey

apiKey: string

Defined in: observability/src/langsmith.ts:6

#endpoint?

optional endpoint?: string

Defined in: observability/src/langsmith.ts:8

#onError?

optional onError?: (error) => void | Promise<void>

Defined in: observability/src/langsmith.ts:10

Isolated error sink; throws/rejections never escape the observer.

#Parameters

error

unknown

#Returns

void | Promise<void>

#projectName?

optional projectName?: string

Defined in: observability/src/langsmith.ts:7

#Interface: LangSmithObserver

Defined in: observability/src/langsmith.ts:13

#Extends

Observer

#Properties

#name

name: string

Defined in: core/dist/chat-DSVPk7dz.d.ts:121

#Inherited from

Observer.name

#on

on: (event) => void | Promise<void>

Defined in: core/dist/chat-DSVPk7dz.d.ts:122

#Parameters

event

AgentEvent

#Returns

void | Promise<void>

#Inherited from

Observer.on

#Methods

#flush()

flush(): Promise<void>

Defined in: observability/src/langsmith.ts:14

#Returns

Promise<void>

#shutdown()

shutdown(): Promise<void>

Defined in: observability/src/langsmith.ts:15

#Returns

Promise<void>

#Interface: LifecycleObserver

Defined in: observability/src/http-batch-sink.ts:5

Shared lifecycle surface for HTTP sinks and SDK bridges.

#Extends

Observer

#Properties

#name

name: string

Defined in: core/dist/chat-DSVPk7dz.d.ts:121

#Inherited from

Observer.name

#on

on: (event) => void | Promise<void>

Defined in: core/dist/chat-DSVPk7dz.d.ts:122

#Parameters

event

AgentEvent

#Returns

void | Promise<void>

#Inherited from

Observer.on

#Methods

#flush()

flush(): Promise<void>

Defined in: observability/src/http-batch-sink.ts:6

#Returns

Promise<void>

#shutdown()

shutdown(): Promise<void>

Defined in: observability/src/http-batch-sink.ts:7

#Returns

Promise<void>

#Interface: MultiTenantCostGuardOptions

Defined in: observability/src/cost-guard-multi-tenant.ts:15

#Properties

#budgets

budgets: Record<string, number>

Defined in: observability/src/cost-guard-multi-tenant.ts:20

Per-tenant USD budgets. Tenants not listed here either inherit defaultBudgetUsd (if set) or are unmetered (no enforcement).

#defaultBudgetUsd?

optional defaultBudgetUsd?: number

Defined in: observability/src/cost-guard-multi-tenant.ts:25

Fallback budget for tenants not explicitly listed in budgets. Omit to make unlisted tenants unmetered.

#modelOverride?

optional modelOverride?: string

Defined in: observability/src/cost-guard-multi-tenant.ts:62

#name?

optional name?: string

Defined in: observability/src/cost-guard-multi-tenant.ts:64

#onCost?

optional onCost?: (info) => void | Promise<void>

Defined in: observability/src/cost-guard-multi-tenant.ts:52

Called whenever a tenant's running total changes. Isolated.

#Parameters

info

budgetRemainingUsd

number | undefined

budgetUsd

number | undefined

completionTokens

number

costUsd

number

promptTokens

number

tenant

string

#Returns

void | Promise<void>

#onError?

optional onError?: CostGuardErrorHandler

Defined in: observability/src/cost-guard-multi-tenant.ts:61

Isolated sink for internal / callback failures.

#onExceeded?

optional onExceeded?: (info) => void | Promise<void>

Defined in: observability/src/cost-guard-multi-tenant.ts:46

Called when a tenant exceeds its budget. The runtime is NOT aborted automatically — multi-tenant deployments typically reject the inbound request at the gateway instead. Wire your own enforcement here (controllers[tenant].abort(), log+drop, send 402, etc.). Sync throws and async rejections are isolated.

#Parameters

info

budgetUsd

number

costUsd

number

tenant

string

#Returns

void | Promise<void>

#prices?

optional prices?: Record<string, TokenPrice>

Defined in: observability/src/cost-guard-multi-tenant.ts:38

Optional price table override.

#tenantOf?

optional tenantOf?: () => string | undefined

Defined in: observability/src/cost-guard-multi-tenant.ts:36

Resolver called on every event. Returns the active tenant id, or undefined to skip metering for this event entirely. The runtime does not propagate tenant ids natively; wire this up with AsyncLocalStorage or by calling setTenant(...) from the returned observer immediately before invoking runtime.run.

Throws are isolated; when the resolver throws, activeTenant is used as fallback when set.

#Returns

string | undefined

#unknownModelPolicy?

optional unknownModelPolicy?: "error" | "allow-zero"

Defined in: observability/src/cost-guard-multi-tenant.ts:63

#Interface: NewRelicSinkConfig

Defined in: observability/src/new-relic.ts:9

Common batching / retry knobs for the three HTTP log sinks.

#Extends

HttpBatchOptions

#Properties

#apiKey

apiKey: string

Defined in: observability/src/new-relic.ts:11

New Relic license / API key (NRAK-... or license key).

#batchSize?

optional batchSize?: number

Defined in: observability/src/http-batch-sink.ts:13

Max events per POST. Default 25. Positive integer.

#Inherited from

HttpBatchOptions.batchSize

#fetch?

optional fetch?: {(input, init?): Promise<Response>; (input, init?): Promise<Response>; }

Defined in: observability/src/http-batch-sink.ts:26

#Call Signature

(input, init?): Promise<Response>

MDN Reference

Parameters

input

RequestInfo | URL

init?

RequestInit

Returns

Promise<Response>

#Call Signature

(input, init?): Promise<Response>

MDN Reference

Parameters

input

string | Request | URL

init?

RequestInit

Returns

Promise<Response>

#Inherited from

HttpBatchOptions.fetch

#flushIntervalMs?

optional flushIntervalMs?: number

Defined in: observability/src/http-batch-sink.ts:17

Periodic drain interval (ms). Default 2000. Finite > 0.

#Inherited from

HttpBatchOptions.flushIntervalMs

#maxQueueSize?

optional maxQueueSize?: number

Defined in: observability/src/http-batch-sink.ts:15

Hard queue cap; drop oldest when full. Default 1000. Positive integer.

#Inherited from

HttpBatchOptions.maxQueueSize

#maxRetries?

optional maxRetries?: number

Defined in: observability/src/http-batch-sink.ts:19

Retries after the initial attempt. Default 3. Integer ≥ 0.

#Inherited from

HttpBatchOptions.maxRetries

#onError?

optional onError?: (error) => void | Promise<void>

Defined in: observability/src/http-batch-sink.ts:25

Isolated error sink; throws/rejections never escape the observer.

#Parameters

error

unknown

#Returns

void | Promise<void>

#Inherited from

HttpBatchOptions.onError

#region?

optional region?: "US" | "EU"

Defined in: observability/src/new-relic.ts:13

Region. 'US' (default) → log-api.newrelic.com, 'EU' → log-api.eu.newrelic.com.

#requestTimeoutMs?

optional requestTimeoutMs?: number

Defined in: observability/src/http-batch-sink.ts:23

Per-request timeout (ms). Default 10000. Positive integer.

#Inherited from

HttpBatchOptions.requestTimeoutMs

#retryBaseDelayMs?

optional retryBaseDelayMs?: number

Defined in: observability/src/http-batch-sink.ts:21

Base backoff delay (ms); doubled each attempt, capped at 30s, no jitter. Default 100.

#Inherited from

HttpBatchOptions.retryBaseDelayMs

#service?

optional service?: string

Defined in: observability/src/new-relic.ts:15

Service name attached to every event.

#Interface: ObserverRedactionOptions

Defined in: observability/src/redaction.ts:28

#Properties

#allowedRoles?

optional allowedRoles?: string[]

Defined in: observability/src/redaction.ts:37

#audit?

optional audit?: RedactionAuditSink

Defined in: observability/src/redaction.ts:38

#mode?

optional mode?: ObserverRedactionMode

Defined in: observability/src/redaction.ts:35

#rules

rules: PIIRule[]

Defined in: observability/src/redaction.ts:34

Rules to apply. Pass DEFAULT_PII_RULES for the baseline set, compilePIITaxonomy(json) for a custom JSON taxonomy, or any hand-rolled PIIRule[].

#vault?

optional vault?: RedactionVault

Defined in: observability/src/redaction.ts:36

#Interface: OpenTelemetryConfig

Defined in: observability/src/opentelemetry.ts:5

#Properties

#endpoint?

optional endpoint?: string

Defined in: observability/src/opentelemetry.ts:6

#onError?

optional onError?: (error) => void | Promise<void>

Defined in: observability/src/opentelemetry.ts:9

Isolated error sink; throws/rejections never escape the observer.

#Parameters

error

unknown

#Returns

void | Promise<void>

#serviceName?

optional serviceName?: string

Defined in: observability/src/opentelemetry.ts:7

#Interface: OpenTelemetryObserver

Defined in: observability/src/opentelemetry.ts:12

#Extends

Observer

#Properties

#name

name: string

Defined in: core/dist/chat-DSVPk7dz.d.ts:121

#Inherited from

Observer.name

#on

on: (event) => void | Promise<void>

Defined in: core/dist/chat-DSVPk7dz.d.ts:122

#Parameters

event

AgentEvent

#Returns

void | Promise<void>

#Inherited from

Observer.on

#Methods

#flush()

flush(): Promise<void>

Defined in: observability/src/opentelemetry.ts:13

#Returns

Promise<void>

#shutdown()

shutdown(): Promise<void>

Defined in: observability/src/opentelemetry.ts:14

#Returns

Promise<void>

#Interface: PiiAuditInput

Defined in: observability/src/audit-log.ts:53

#Properties

#action

action: PiiAuditAction

Defined in: observability/src/audit-log.ts:55

#actor

actor: string

Defined in: observability/src/audit-log.ts:54

#hits

hits: readonly PIIRedactionHit[]

Defined in: observability/src/audit-log.ts:57

#reason?

optional reason?: string

Defined in: observability/src/audit-log.ts:58

#subjectId?

optional subjectId?: string

Defined in: observability/src/audit-log.ts:56

#Interface: PiiAuditPayload

Defined in: observability/src/audit-log.ts:61

#Properties

#count

count: number

Defined in: observability/src/audit-log.ts:64

#matches

matches: object[]

Defined in: observability/src/audit-log.ts:65

#length

length: number

#offset

offset: number

#reason?

optional reason?: string

Defined in: observability/src/audit-log.ts:66

#rule

rule: string

Defined in: observability/src/audit-log.ts:63

#subjectId?

optional subjectId?: string

Defined in: observability/src/audit-log.ts:62

#Interface: ProviderTokenCounterOptions

Defined in: observability/src/token-counter.ts:125

Options for creating a provider-specific token counter.

#Properties

#name

name: string

Defined in: observability/src/token-counter.ts:143

Human-readable name for this counter.

#perMessageOverhead?

optional perMessageOverhead?: number

Defined in: observability/src/token-counter.ts:145

Per-message overhead in tokens. Defaults to 4.

#tokenize

tokenize: (text, model?) => readonly unknown[] | Promise<readonly unknown[]>

Defined in: observability/src/token-counter.ts:141

The tokenize function from a provider-specific tokenizer library. Must return an array of token ids (or any array whose .length represents the token count).

#Parameters

text

string

model?

string

#Returns

readonly unknown[] | Promise<readonly unknown[]>

#Example

import { encoding_for_model } from 'tiktoken'
const enc = encoding_for_model('gpt-4o')
const counter = createProviderCounter({
  name: 'tiktoken',
  tokenize: (text) => [...enc.encode(text)],
})

#Interface: RunSnapshot

Defined in: observability/src/prod-control.ts:36

#Properties

#capturedAt

capturedAt: string

Defined in: observability/src/prod-control.ts:39

ISO timestamp.

#events

events: AgentEvent[]

Defined in: observability/src/prod-control.ts:44

Verbatim recent events for the run (capped).

#metadata?

optional metadata?: Record<string, unknown>

Defined in: observability/src/prod-control.ts:48

Free-form metadata you want to ship with the support ticket.

#overrides

overrides: ToolOverride[]

Defined in: observability/src/prod-control.ts:46

Pending tool overrides.

#paused

paused: boolean

Defined in: observability/src/prod-control.ts:40

#runId

runId: string

Defined in: observability/src/prod-control.ts:37

#seq

seq: number

Defined in: observability/src/prod-control.ts:42

Last seq number observed for the run.

#Interface: SignedAuditLog

Defined in: observability/src/audit-log.ts:45

#Properties

#append

append: <TPayload>(input) => Promise<AuditEntry<TPayload>>

Defined in: observability/src/audit-log.ts:46

#Type Parameters

TPayload

TPayload

#Parameters

input

AppendAuditInput<TPayload>

#Returns

Promise<AuditEntry<TPayload>>

#list

list: () => Promise<AuditEntry<unknown>[]>

Defined in: observability/src/audit-log.ts:48

#Returns

Promise<AuditEntry<unknown>[]>

#verify

verify: () => Promise<AuditVerifyResult>

Defined in: observability/src/audit-log.ts:47

#Returns

Promise<AuditVerifyResult>

#Interface: SloObserver

Defined in: observability/src/slo.ts:84

#Extends

Observer

#Properties

#name

name: string

Defined in: core/dist/chat-DSVPk7dz.d.ts:121

#Inherited from

Observer.name

#on

on: (event) => void | Promise<void>

Defined in: core/dist/chat-DSVPk7dz.d.ts:122

#Parameters

event

AgentEvent

#Returns

void | Promise<void>

#Inherited from

Observer.on

#otel

otel: () => object[]

Defined in: observability/src/slo.ts:89

OpenTelemetry-shaped metric records (push to OTLP).

#Returns

object[]

#prometheus

prometheus: () => string

Defined in: observability/src/slo.ts:87

Prometheus exposition text (# HELP / # TYPE / metric\{...\} value).

#Returns

string

#snapshot

snapshot: (windowMs?) => SloSnapshot

Defined in: observability/src/slo.ts:85

#Parameters

windowMs?

number

#Returns

SloSnapshot

#stop

stop: () => void

Defined in: observability/src/slo.ts:91

Stop the burn-rate timer.

#Returns

void

#Interface: SloOptions

Defined in: observability/src/slo.ts:35

#Properties

#alert?

optional alert?: CostAlertSink

Defined in: observability/src/slo.ts:42

Alert sink. Same contract as cost-guard alerts so a single sink can fan-in.

#burnRateWindowsMs?

optional burnRateWindowsMs?: number[]

Defined in: observability/src/slo.ts:40

Burn-rate windows. Default [3_600_000, 21_600_000] (1h, 6h).

#now?

optional now?: () => number

Defined in: observability/src/slo.ts:44

Wall clock — overridable for tests.

#Returns

number

#stallThresholdMs?

optional stallThresholdMs?: number

Defined in: observability/src/slo.ts:38

First-token latency above this counts as a stall. Default 8000ms.

#targets?

optional targets?: SloTargets

Defined in: observability/src/slo.ts:36

#Interface: SloSnapshot

Defined in: observability/src/slo.ts:73

#Properties

#latencyP50Ms

latencyP50Ms: number

Defined in: observability/src/slo.ts:77

#latencyP95Ms

latencyP95Ms: number

Defined in: observability/src/slo.ts:78

#latencyP99Ms

latencyP99Ms: number

Defined in: observability/src/slo.ts:79

#streamingStallRate

streamingStallRate: number

Defined in: observability/src/slo.ts:81

#successRate

successRate: number

Defined in: observability/src/slo.ts:76

#toolErrorRate

toolErrorRate: number

Defined in: observability/src/slo.ts:80

#total

total: number

Defined in: observability/src/slo.ts:75

#windowMs

windowMs: number

Defined in: observability/src/slo.ts:74

#Interface: SloTargets

Defined in: observability/src/slo.ts:24

SLO preset for AgentsKit. Tracks the four metrics that matter for an agent runtime in production:

success rate (per agent / per skill / per tool)
p50 / p95 / p99 latency
tool-error rate
streaming-stall rate (first-token latency above threshold)

Operates on canonical AgentEvent. Correlation is optional; when it is not available, in-flight operations are tracked as a single active op under the sequential event-stream assumption.

Exposes Prometheus + OpenTelemetry-shaped snapshots and burn-rate alerts (1h + 6h windows) that fire into the same alert sink contract the cost guard already uses (CostAlertSink-compatible payloads).

Closes issue #796.

#Properties

#latencyP95Ms?

optional latencyP95Ms?: number

Defined in: observability/src/slo.ts:28

Milliseconds. Default 5000.

#streamingStallRate?

optional streamingStallRate?: number

Defined in: observability/src/slo.ts:32

0–1. Default 0.005.

#successRate?

optional successRate?: number

Defined in: observability/src/slo.ts:26

0–1. Default 0.99.

#toolErrorRate?

optional toolErrorRate?: number

Defined in: observability/src/slo.ts:30

0–1. Default 0.01.

#Interface: TokenPrice

Defined in: observability/src/cost-guard.ts:6

Dollar cost per 1K tokens for input and output.

#Properties

#input

input: number

Defined in: observability/src/cost-guard.ts:7

#output

output: number

Defined in: observability/src/cost-guard.ts:8

#Interface: ToolOverride

Defined in: observability/src/prod-control.ts:21

Production agent control surface. Devtools (#35) is dev-only; this is the auth-gated production counterpart that lets ops:

pause an agent loop
step a paused loop one iteration
inject tool overrides for the next call to a tool
snapshot the current state for support tickets
replay from a previously-captured snapshot

Designed as a transport-agnostic engine — the same ControlSurface sits behind an HTTP endpoint, an MCP server, or in-process tests. httpHandler() ships a bearer-token-gated REST surface so a default deployment is one createServer(handler) call.

Closes issue #784.

#Properties

#reason?

optional reason?: string

Defined in: observability/src/prod-control.ts:33

Audit note included in the snapshot + audit log.

#result

result: string

Defined in: observability/src/prod-control.ts:29

Forced result. The runtime should return this verbatim instead of running the tool's execute(). Single-shot — consumed by the first matching tool call after injection.

#status?

optional status?: "error" | "complete"

Defined in: observability/src/prod-control.ts:31

Optional: also mark the call status. Defaults to 'complete'.

#tool

tool: string

Defined in: observability/src/prod-control.ts:23

Tool to override on the next call.

#Interface: TopologyEdge

Defined in: observability/src/topology-graph.ts:44

#Properties

#count

count: number

Defined in: observability/src/topology-graph.ts:50

Number of times this edge fired.

#from

from: string

Defined in: observability/src/topology-graph.ts:47

#id

id: string

Defined in: observability/src/topology-graph.ts:46

from→to (stable id).

#lastResult?

optional lastResult?: string

Defined in: observability/src/topology-graph.ts:53

#lastTask?

optional lastTask?: string

Defined in: observability/src/topology-graph.ts:52

Most recent task/result snippet (trimmed) — useful for tooltips.

#to

to: string

Defined in: observability/src/topology-graph.ts:48

#Interface: TopologyGraph

Defined in: observability/src/topology-graph.ts:56

#Properties

#edges

edges: Map<string, TopologyEdge>

Defined in: observability/src/topology-graph.ts:58

#ingest

ingest: (event) => void

Defined in: observability/src/topology-graph.ts:63

Send a TopologyLogEvent into the graph. Mutates state. Calls every subscriber after each event.

#Parameters

event

TopologyLogEvent

#Returns

void

#nodes

nodes: Map<string, TopologyNode>

Defined in: observability/src/topology-graph.ts:57

#reset

reset: () => void

Defined in: observability/src/topology-graph.ts:73

Reset to empty (e.g. when a new run starts).

#Returns

void

subscribe: (handler) => () => void

Defined in: observability/src/topology-graph.ts:71

Subscribe to graph changes. Returns an unsubscribe handle.

#Parameters

handler

(snapshot) => void

#Returns

() => void

#toAscii

toAscii: () => string

Defined in: observability/src/topology-graph.ts:69

ASCII renderer (Ink-friendly).

#Returns

string

#toJSON

toJSON: () => TopologyGraphSnapshot

Defined in: observability/src/topology-graph.ts:65

Snapshot in a JSON-serialisable form for the devtools wire.

#Returns

TopologyGraphSnapshot

#toMermaid

toMermaid: () => string

Defined in: observability/src/topology-graph.ts:67

Mermaid graph LR diagram.

#Returns

string

#Interface: TopologyGraphOptions

Defined in: observability/src/topology-graph.ts:83

#Properties

#now?

optional now?: () => number

Defined in: observability/src/topology-graph.ts:87

Wall clock — overridable for tests.

#Returns

number

#snippetLength?

optional snippetLength?: number

Defined in: observability/src/topology-graph.ts:85

Truncation length for task/result tooltips. Default 80.

#Interface: TopologyGraphSnapshot

Defined in: observability/src/topology-graph.ts:76

#Properties

#edges

edges: TopologyEdge[]

Defined in: observability/src/topology-graph.ts:78

#nodes

nodes: TopologyNode[]

Defined in: observability/src/topology-graph.ts:77

#updatedAt

updatedAt: string

Defined in: observability/src/topology-graph.ts:80

ISO timestamp of the latest event.

#Interface: TopologyLogEvent

Defined in: observability/src/topology-graph.ts:6

Mirrors the TopologyLogEvent shape from @agentskit/runtime. We redefine it here to avoid a runtime → observability dependency cycle; the contract is stable (defined alongside topologies.ts).

#Properties

#agent?

optional agent?: string

Defined in: observability/src/topology-graph.ts:9

#iteration?

optional iteration?: number

Defined in: observability/src/topology-graph.ts:12

#phase

phase: "dispatch" | "agent:start" | "agent:end" | "merge" | "done"

Defined in: observability/src/topology-graph.ts:8

#result?

optional result?: string

Defined in: observability/src/topology-graph.ts:11

#task?

optional task?: string

Defined in: observability/src/topology-graph.ts:10

#topology

topology: string

Defined in: observability/src/topology-graph.ts:7

#Interface: TopologyNode

Defined in: observability/src/topology-graph.ts:30

Live multi-agent topology graph. Consumes TopologyLogEvents from supervisor / swarm / hierarchical / blackboard runs and builds a directed graph of agents and the messages flowing between them, so debugging multi-agent runs stops being a tail of stringly-typed logs.

Renders to:

JSON — for the React devtools panel
Mermaid — for static docs / CI artefacts
ASCII — for the Ink CLI

Closes issue #785.

#Properties

#endCount

endCount: number

Defined in: observability/src/topology-graph.ts:38

#errorCount

errorCount: number

Defined in: observability/src/topology-graph.ts:39

#id

id: string

Defined in: observability/src/topology-graph.ts:31

#label

label: string

Defined in: observability/src/topology-graph.ts:33

Display label. Defaults to the agent id.

#lastActiveAt

lastActiveAt: number

Defined in: observability/src/topology-graph.ts:41

Last activity timestamp (ms since epoch).

#startCount

startCount: number

Defined in: observability/src/topology-graph.ts:37

Activity counters useful for sizing/colouring nodes in a viz.

#topology

topology: string

Defined in: observability/src/topology-graph.ts:35

'supervisor' | 'swarm' | 'hierarchical' | 'blackboard'.

#Interface: TraceReport

Defined in: observability/src/trace-viewer.ts:4

#Properties

#durationMs

durationMs: number

Defined in: observability/src/trace-viewer.ts:8

#endTime

endTime: number

Defined in: observability/src/trace-viewer.ts:7

#errorCount

errorCount: number

Defined in: observability/src/trace-viewer.ts:10

#spanCount

spanCount: number

Defined in: observability/src/trace-viewer.ts:9

#spans

spans: TraceSpan[]

Defined in: observability/src/trace-viewer.ts:11

#startTime

startTime: number

Defined in: observability/src/trace-viewer.ts:6

#traceId

traceId: string

Defined in: observability/src/trace-viewer.ts:5

#Interface: TraceSpan

Defined in: observability/src/trace-tracker.ts:14

#Properties

#attributes

attributes: Record<string, unknown>

Defined in: observability/src/trace-tracker.ts:20

#endTime?

optional endTime?: number

Defined in: observability/src/trace-tracker.ts:19

#id

id: string

Defined in: observability/src/trace-tracker.ts:15

#name

name: string

Defined in: observability/src/trace-tracker.ts:16

#parentId

parentId: string | null

Defined in: observability/src/trace-tracker.ts:17

#startTime

startTime: number

Defined in: observability/src/trace-tracker.ts:18

#status

status: "ok" | "error"

Defined in: observability/src/trace-tracker.ts:21

#Interface: TraceTrackerCallbacks

Defined in: observability/src/trace-tracker.ts:24

#Properties

#onSpanEnd

onSpanEnd: (span) => void

Defined in: observability/src/trace-tracker.ts:26

#Parameters

span

TraceSpan

#Returns

void

#onSpanStart

onSpanStart: (span) => void

Defined in: observability/src/trace-tracker.ts:25

#Parameters

span

TraceSpan

#Returns

void

#Interface: WebhookAlertSinkOptions

Defined in: observability/src/cost-guard-alert-sinks.ts:21

#Properties

#fetch?

optional fetch?: {(input, init?): Promise<Response>; (input, init?): Promise<Response>; }

Defined in: observability/src/cost-guard-alert-sinks.ts:24

Override fetch (tests / custom clients).

#Call Signature

(input, init?): Promise<Response>

MDN Reference

#Call Signature

(input, init?): Promise<Response>

MDN Reference

#headers?

optional headers?: Record<string, string>

Defined in: observability/src/cost-guard-alert-sinks.ts:26

Optional bearer / signing header.

#url

url: string

Defined in: observability/src/cost-guard-alert-sinks.ts:22

Explore nearby

✎ Edit this page on GitHub·Found a problem? Open an issue →·How to contribute →