@agentskit/observability β Interfaces
API interfaces for @agentskit/observability.
#Interface: AdvancedCostGuard
Defined in: packages/observability/src/cost-guard-advanced.ts:47
Observer interface and per-tenant controls returned by createAdvancedCostGuard.
#Extends
Observer
#Properties
#costUsd
costUsd: (
tenant) =>number
Defined in: packages/observability/src/cost-guard-advanced.ts:49
#Parameters
tenant
string
#Returns
number
#enable
enable: (
tenant) =>void
Defined in: packages/observability/src/cost-guard-advanced.ts:60
Re-enable a tenant disabled by kill mode. Caller must also clear the persisted flag.
#Parameters
tenant
string
#Returns
void
#isDisabled
isDisabled: (
tenant) =>boolean
Defined in: packages/observability/src/cost-guard-advanced.ts:51
#Parameters
tenant
string
#Returns
boolean
#isRejected
isRejected: (
tenant) =>boolean
Defined in: packages/observability/src/cost-guard-advanced.ts:58
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: packages/core/dist/chat-C1aW2_Tp.d.ts:131
#Inherited from
Observer.name
#on
on: (
event) =>void|Promise<void>
Defined in: packages/core/dist/chat-C1aW2_Tp.d.ts:132
#Parameters
event
AgentEvent
#Returns
void | Promise<void>
#Inherited from
Observer.on
#reset
reset: (
tenant?) =>void
Defined in: packages/observability/src/cost-guard-advanced.ts:61
#Parameters
tenant?
string
#Returns
void
#setTenant
setTenant: (
tenant) =>void
Defined in: packages/observability/src/cost-guard-advanced.ts:48
#Parameters
tenant
string | undefined
#Returns
void
#tenants
tenants: () =>
string[]
Defined in: packages/observability/src/cost-guard-advanced.ts:62
#Returns
string[]
#windowSpend
windowSpend: (
tenant,window) =>number|undefined
Defined in: packages/observability/src/cost-guard-advanced.ts:50
#Parameters
tenant
string
window
string
#Returns
number | undefined
#Interface: AdvancedCostGuardOptions
Defined in: packages/observability/src/cost-guard-advanced-types.ts:60
Configuration for per-tenant budgets, rolling caps, and enforcement.
#Extends
#Properties
#alertSinks?
optionalalertSinks?:CostAlertSink[]
Defined in: packages/observability/src/cost-guard-advanced-types.ts:86
One or more alert sinks. Fired in registration order.
#budgets
budgets:
Record<string,number>
Defined in: packages/observability/src/cost-guard-advanced-types.ts:62
Per-tenant USD budgets (overall, applied alongside windows).
#caps?
optionalcaps?:CostCaps
Defined in: packages/observability/src/cost-guard-advanced-types.ts:66
Window caps applied to every tenant. Per-tenant overrides via tenantCaps.
#defaultBudgetUsd?
optionaldefaultBudgetUsd?:number
Defined in: packages/observability/src/cost-guard-advanced-types.ts:64
Fallback overall budget for tenants not listed.
#disableRuntime?
optionaldisableRuntime?: (tenant,reason) =>void|Promise<void>
Defined in: packages/observability/src/cost-guard-advanced-types.ts:84
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?
optionalmode?:CostGuardMode
Defined in: packages/observability/src/cost-guard-advanced-types.ts:76
Enforcement mode (default 'warn'). 'kill' requires
disableRuntime.
#modelOverride?
optionalmodelOverride?:string
Defined in: packages/observability/src/cost-guard-advanced-types.ts:89
#name?
optionalname?:string
Defined in: packages/observability/src/cost-guard-advanced-types.ts:93
#now?
optionalnow?: () =>number
Defined in: packages/observability/src/cost-guard-advanced-types.ts:92
Clock override for tests. Throws / non-finite values are isolated.
#Returns
number
#onError?
optionalonError?:CostGuardErrorHandler
Defined in: packages/observability/src/cost-guard-advanced-types.ts:88
Isolated sink for internal / callback / sink failures.
#prices?
optionalprices?:Record<string,TokenPrice>
Defined in: packages/observability/src/cost-guard-advanced-types.ts:71
#store?
optionalstore?:CostStore
Defined in: packages/observability/src/cost-guard-store.ts:12
Durable store that receives every priced call. With it, the budget is checked against spend recorded by all instances in the store's current window; without it, totals live in process memory (development only; warns in production).
#Inherited from
#tenantCaps?
optionaltenantCaps?:Record<string,CostCaps>
Defined in: packages/observability/src/cost-guard-advanced-types.ts:68
Per-tenant override of caps. Wins over the workspace-wide caps.
#tenantOf?
optionaltenantOf?: () =>string|undefined
Defined in: packages/observability/src/cost-guard-advanced-types.ts:70
Active tenant resolver (same shape as multiTenantCostGuard.tenantOf).
#Returns
string | undefined
#unknownModelPolicy?
optionalunknownModelPolicy?:UnknownModelPolicy
Defined in: packages/observability/src/cost-guard-advanced-types.ts:90
#warnWithoutStore?
optionalwarnWithoutStore?:boolean
Defined in: packages/observability/src/cost-guard-store.ts:18
Controls the warning for a guard that runs without a store. By default it
warns when NODE_ENV is production, and on Cloudflare Workers when
NODE_ENV is not set. true always warns; false silences it.
#Inherited from
CostGuardStoreOptions.warnWithoutStore
#Interface: AppendAuditInput<TPayload>
Defined in: packages/observability/src/audit-log.ts:36
Caller-supplied values for one audit record.
#Type Parameters
#TPayload
TPayload = unknown
#Properties
#action
action:
string
Defined in: packages/observability/src/audit-log.ts:38
#actor
actor:
string
Defined in: packages/observability/src/audit-log.ts:37
#payload
payload:
TPayload
Defined in: packages/observability/src/audit-log.ts:39
#Interface: AuditEntry<TPayload>
Defined in: packages/observability/src/audit-log.ts:5
Signed, sequence-numbered audit record linked to its predecessor.
#Type Parameters
#TPayload
TPayload = unknown
#Properties
#action
action:
string
Defined in: packages/observability/src/audit-log.ts:10
#actor
actor:
string
Defined in: packages/observability/src/audit-log.ts:9
#payload
payload:
TPayload
Defined in: packages/observability/src/audit-log.ts:11
#prevHash
prevHash:
string
Defined in: packages/observability/src/audit-log.ts:13
Hex SHA-256 of the previous entry's canonical form. '' for seq 1.
#seq
seq:
number
Defined in: packages/observability/src/audit-log.ts:7
Monotonic sequence within a log. Starts at 1.
#signature
signature:
string
Defined in: packages/observability/src/audit-log.ts:15
Hex HMAC of the canonical form of this entry (including prevHash).
#timestamp
timestamp:
string
Defined in: packages/observability/src/audit-log.ts:8
#Interface: AuditLogOptions
Defined in: packages/observability/src/audit-log.ts:27
Secret, storage, and clock settings for a signed audit log.
#Properties
#now?
optionalnow?: () =>Date
Defined in: packages/observability/src/audit-log.ts:32
Clock override for tests.
#Returns
Date
#secret
secret:
string
Defined in: packages/observability/src/audit-log.ts:29
HMAC secret β rotate out-of-band.
#store
store:
AuditLogStore
Defined in: packages/observability/src/audit-log.ts:30
#Interface: AuditLogStore
Defined in: packages/observability/src/audit-log.ts:19
Append-only storage operations required by the signed audit log.
#Properties
#append
append: (
entry) =>Promise<void>
Defined in: packages/observability/src/audit-log.ts:20
#Parameters
entry
#Returns
Promise<void>
#clear?
optionalclear?: () =>Promise<void>
Defined in: packages/observability/src/audit-log.ts:23
#Returns
Promise<void>
#last
last: () =>
Promise<AuditEntry<unknown> |null>
Defined in: packages/observability/src/audit-log.ts:22
#Returns
Promise<AuditEntry<unknown> | null>
#list
list: () =>
Promise<AuditEntry<unknown>[]>
Defined in: packages/observability/src/audit-log.ts:21
#Returns
Promise<AuditEntry<unknown>[]>
#Interface: AuditVerifyResult
Defined in: packages/observability/src/audit-log.ts:43
Result of validating audit entry signatures and hash links.
#Properties
#brokenAt?
optionalbrokenAt?:object
Defined in: packages/observability/src/audit-log.ts:46
First entry where the chain broke, or null when ok.
#reason
reason:
"prev-hash"|"signature"
#seq
seq:
number
#entryCount
entryCount:
number
Defined in: packages/observability/src/audit-log.ts:47
#ok
ok:
boolean
Defined in: packages/observability/src/audit-log.ts:44
#Interface: AxiomSinkConfig
Defined in: packages/observability/src/axiom.ts:10
Axiom dataset credentials, endpoint, service label, and batch settings.
#Extends
#Properties
#batchSize?
optionalbatchSize?:number
Defined in: packages/observability/src/http-batch-sink.ts:14
Max events per POST. Default 25. Positive integer.
#Inherited from
#dataset
dataset:
string
Defined in: packages/observability/src/axiom.ts:14
Dataset name to write into.
#endpoint?
optionalendpoint?:string
Defined in: packages/observability/src/axiom.ts:16
Override the ingest endpoint (e.g. EU region: https://api.eu.axiom.co).
#fetch?
optionalfetch?: {(input,init?):Promise<Response>; (input,init?):Promise<Response>; }
Defined in: packages/observability/src/http-batch-sink.ts:27
#Call Signature
(
input,init?):Promise<Response>
Parameters
input
RequestInfo | URL
init?
RequestInit
Returns
Promise<Response>
#Call Signature
(
input,init?):Promise<Response>
Parameters
input
string | Request | URL
init?
RequestInit
Returns
Promise<Response>
#Inherited from
#flushIntervalMs?
optionalflushIntervalMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:18
Periodic drain interval (ms). Default 2000. Finite > 0.
#Inherited from
HttpBatchOptions.flushIntervalMs
#maxQueueSize?
optionalmaxQueueSize?:number
Defined in: packages/observability/src/http-batch-sink.ts:16
Hard queue cap; drop oldest when full. Default 1000. Positive integer.
#Inherited from
#maxRetries?
optionalmaxRetries?:number
Defined in: packages/observability/src/http-batch-sink.ts:20
Retries after the initial attempt. Default 3. Integer β₯ 0.
#Inherited from
#onError?
optionalonError?: (error) =>void|Promise<void>
Defined in: packages/observability/src/http-batch-sink.ts:26
Isolated error sink; throws/rejections never escape the observer.
#Parameters
error
unknown
#Returns
void | Promise<void>
#Inherited from
#requestTimeoutMs?
optionalrequestTimeoutMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:24
Per-request timeout (ms). Default 10000. Positive integer.
#Inherited from
HttpBatchOptions.requestTimeoutMs
#retryBaseDelayMs?
optionalretryBaseDelayMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:22
Base delay (ms); full-jitter exponential retries capped at 30s; valid Retry-After is honored as a minimum, also capped. Default 100.
#Inherited from
HttpBatchOptions.retryBaseDelayMs
#service?
optionalservice?:string
Defined in: packages/observability/src/axiom.ts:18
Service name attached to every event.
#token
token:
string
Defined in: packages/observability/src/axiom.ts:12
Axiom API token.
#Interface: ChargebackReport
Defined in: packages/observability/src/cost-chargeback.ts:79
Aggregated chargeback rows and totals for the requested window.
#Properties
#from?
optionalfrom?:string
Defined in: packages/observability/src/cost-chargeback.ts:87
Window the report covers (whichever the caller passed).
#groupBy
groupBy:
ChargebackGroupKey
Defined in: packages/observability/src/cost-chargeback.ts:80
#rows
rows:
ChargebackRow[]
Defined in: packages/observability/src/cost-chargeback.ts:81
#to?
optionalto?:string
Defined in: packages/observability/src/cost-chargeback.ts:88
#totalCalls
totalCalls:
number
Defined in: packages/observability/src/cost-chargeback.ts:85
Sum of callCount across all rows.
#totalCostUsd
totalCostUsd:
number
Defined in: packages/observability/src/cost-chargeback.ts:83
Sum of costUsd across all rows.
#Interface: ChargebackReportOptions
Defined in: packages/observability/src/cost-chargeback.ts:50
Grouping, pricing, and inclusive time-window options for a chargeback report.
#Properties
#from?
optionalfrom?:string
Defined in: packages/observability/src/cost-chargeback.ts:59
Inclusive window filter (ISO 8601). Samples outside the window are dropped before grouping.
#groupBy?
optionalgroupBy?:ChargebackGroupKey
Defined in: packages/observability/src/cost-chargeback.ts:52
Group key. Default 'tenant'.
#prices?
optionalprices?:Record<string,TokenPrice>
Defined in: packages/observability/src/cost-chargeback.ts:54
Optional price table override for sample cost computation.
#to?
optionalto?:string
Defined in: packages/observability/src/cost-chargeback.ts:60
#Interface: ChargebackRow
Defined in: packages/observability/src/cost-chargeback.ts:64
Aggregated token and spend totals for one chargeback group.
#Properties
#callCount
callCount:
number
Defined in: packages/observability/src/cost-chargeback.ts:67
#completionTokens
completionTokens:
number
Defined in: packages/observability/src/cost-chargeback.ts:69
#costUsd
costUsd:
number
Defined in: packages/observability/src/cost-chargeback.ts:71
#firstAt
firstAt:
string
Defined in: packages/observability/src/cost-chargeback.ts:73
Earliest sample timestamp in the group (ISO 8601).
#group
group:
string
Defined in: packages/observability/src/cost-chargeback.ts:66
Composite group key, joined with '/' for multi-field groups.
#lastAt
lastAt:
string
Defined in: packages/observability/src/cost-chargeback.ts:75
Latest sample timestamp in the group (ISO 8601).
#promptTokens
promptTokens:
number
Defined in: packages/observability/src/cost-chargeback.ts:68
#totalTokens
totalTokens:
number
Defined in: packages/observability/src/cost-chargeback.ts:70
#Interface: ConsoleLoggerConfig
Defined in: packages/observability/src/console-logger.ts:5
Output format for the console event logger.
#Properties
#format?
optionalformat?:"human"|"json"
Defined in: packages/observability/src/console-logger.ts:6
#Interface: ControlAuditEntry
Defined in: packages/observability/src/prod-control.ts:62
Audit record for a production control action.
#Properties
#action
action:
"pause"|"resume"|"step"|"inject"|"snapshot"|"replay"
Defined in: packages/observability/src/prod-control.ts:65
#actor?
optionalactor?:string
Defined in: packages/observability/src/prod-control.ts:68
Authenticated principal id, if available.
#at
at:
string
Defined in: packages/observability/src/prod-control.ts:64
ISO timestamp.
#payload?
optionalpayload?:Record<string,unknown>
Defined in: packages/observability/src/prod-control.ts:70
Action-specific payload (override details, snapshot id, etc).
#runId
runId:
string
Defined in: packages/observability/src/prod-control.ts:66
#Interface: ControlSurface
Defined in: packages/observability/src/prod-control.ts:74
Runtime hooks and administrative controls returned by createControlSurface.
#Properties
#awaitResume
awaitResume: (
runId) =>Promise<void>
Defined in: packages/observability/src/prod-control.ts:95
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: packages/observability/src/prod-control.ts:101
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: packages/observability/src/prod-control.ts:89
Release retained events, overrides, and waiters for a run.
#Parameters
runId
string
#Returns
void
#httpHandler
httpHandler: () => (
req) =>Promise<{body:unknown;status:number; }>
Defined in: packages/observability/src/prod-control.ts:106
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: packages/observability/src/prod-control.ts:83
Inject a tool override consumed by the next matching tool call.
#Parameters
runId
string
override
actor?
string
#Returns
void
#observer
observer:
Observer
Defined in: packages/observability/src/prod-control.ts:76
Plug into createRuntime(\{ observers: [control.observer] \}).
#pause
pause: (
runId,actor?) =>void
Defined in: packages/observability/src/prod-control.ts:78
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: packages/observability/src/prod-control.ts:87
Restore a snapshot's pending overrides + paused state. Replay events are NOT reused β replay against your own runtime.
#Parameters
snapshot
actor?
string
#Returns
void
#resume
resume: (
runId,actor?) =>void
Defined in: packages/observability/src/prod-control.ts:79
#Parameters
runId
string
actor?
string
#Returns
void
#snapshot
snapshot: (
runId,metadata?) =>RunSnapshot
Defined in: packages/observability/src/prod-control.ts:85
Capture a snapshot for a support ticket.
#Parameters
runId
string
metadata?
Record<string, unknown>
#Returns
#step
step: (
runId,actor?) =>void
Defined in: packages/observability/src/prod-control.ts:81
Allow exactly one more iteration on a paused run.
#Parameters
runId
string
actor?
string
#Returns
void
#Interface: ControlSurfaceOptions
Defined in: packages/observability/src/prod-control.ts:37
Retention, run correlation, audit, and HTTP authentication settings.
#Properties
#audit?
optionalaudit?: (entry) =>void
Defined in: packages/observability/src/prod-control.ts:46
Audit log sink β gets every control action.
#Parameters
entry
#Returns
void
#bearerToken?
optionalbearerToken?:string
Defined in: packages/observability/src/prod-control.ts:44
Bearer token required for HTTP access. Required when using
httpHandler(). Compared with constant-time equality.
#defaultRunId?
optionaldefaultRunId?:string
Defined in: packages/observability/src/prod-control.ts:56
Fallback run id when neither runIdOf nor enriched top-level
runId/id fields are present on the event.
#maxRuns?
optionalmaxRuns?:number
Defined in: packages/observability/src/prod-control.ts:58
Maximum number of run states retained in memory. Default 1000.
#runIdOf?
optionalrunIdOf?: (event) =>string|undefined
Defined in: packages/observability/src/prod-control.ts:51
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?
optionalsnapshotBufferSize?:number
Defined in: packages/observability/src/prod-control.ts:39
Max events retained per run for snapshots. Default 200.
#Interface: CostAlertEvent
Defined in: packages/observability/src/cost-guard-advanced-types.ts:32
JSON-safe details for a cost guard alert.
#Properties
#at
at:
string
Defined in: packages/observability/src/cost-guard-advanced-types.ts:38
ISO 8601 timestamp.
#budgetUsd
budgetUsd:
number
Defined in: packages/observability/src/cost-guard-advanced-types.ts:42
Cap for this window (USD).
#costUsd
costUsd:
number
Defined in: packages/observability/src/cost-guard-advanced-types.ts:40
Spend so far in this window (USD).
#msUntilExceeded?
optionalmsUntilExceeded?:number
Defined in: packages/observability/src/cost-guard-advanced-types.ts:51
Estimated milliseconds until the budget is exhausted at the
current spend rate, when type is 'cost:forecast'.
#reason?
optionalreason?:string
Defined in: packages/observability/src/cost-guard-advanced-types.ts:53
Optional human-readable reason (mode change, etc.).
#tenant
tenant:
string
Defined in: packages/observability/src/cost-guard-advanced-types.ts:34
#threshold?
optionalthreshold?:number
Defined in: packages/observability/src/cost-guard-advanced-types.ts:46
Threshold that triggered this alert (0.5, 0.8, 1.0, or undefined for forecast).
#type
type:
CostAlertType
Defined in: packages/observability/src/cost-guard-advanced-types.ts:33
#utilization
utilization:
number
Defined in: packages/observability/src/cost-guard-advanced-types.ts:44
Fraction of budget consumed (0ββ, always finite).
#window
window:
string
Defined in: packages/observability/src/cost-guard-advanced-types.ts:36
Window id ('perMinute', 'perDay', 'perMonth', custom name).
#Interface: CostCaps
Defined in: packages/observability/src/cost-guard-advanced-types.ts:16
Named rolling spend limits applied to a tenant.
#Properties
#custom?
optionalcustom?:Record<string,CostCapWindow>
Defined in: packages/observability/src/cost-guard-advanced-types.ts:21
Custom additional windows.
#perDay?
optionalperDay?:CostCapWindow
Defined in: packages/observability/src/cost-guard-advanced-types.ts:18
#perMinute?
optionalperMinute?:CostCapWindow
Defined in: packages/observability/src/cost-guard-advanced-types.ts:17
#perMonth?
optionalperMonth?:CostCapWindow
Defined in: packages/observability/src/cost-guard-advanced-types.ts:19
#Interface: CostCapWindow
Defined in: packages/observability/src/cost-guard-advanced-types.ts:8
Spend limit and rolling duration for one cost cap.
#Properties
#budgetUsd
budgetUsd:
number
Defined in: packages/observability/src/cost-guard-advanced-types.ts:12
USD ceiling per window.
#windowMs
windowMs:
number
Defined in: packages/observability/src/cost-guard-advanced-types.ts:10
Window length in milliseconds.
#Interface: CostCommitInput
Defined in: packages/observability/src/cost-store.ts:50
Input of CostStore.commit.
#Properties
#actualUsd
actualUsd:
number
Defined in: packages/observability/src/cost-store.ts:54
Real spend in USD. Replaces the reserved amount, and may exceed it.
#reservationId
reservationId:
string
Defined in: packages/observability/src/cost-store.ts:52
#tenant
tenant:
string
Defined in: packages/observability/src/cost-store.ts:51
#usage?
optionalusage?: readonlyCostUsageEntry[]
Defined in: packages/observability/src/cost-store.ts:56
Ledger rows for the calls that produced actualUsd.
#Interface: CostGuardOptions
Defined in: packages/observability/src/cost-guard.ts:53
Configuration for an observer that tracks cumulative token spend.
#Extends
#Properties
#budgetUsd
budgetUsd:
number
Defined in: packages/observability/src/cost-guard.ts:57
Hard budget in USD. Aborts the run when exceeded.
#controller
controller:
AbortController
Defined in: packages/observability/src/cost-guard.ts:62
AbortController to signal the runtime to stop. The runtime picks this up via RunOptions.signal (RT13).
#modelOverride?
optionalmodelOverride?:string
Defined in: packages/observability/src/cost-guard.ts:85
Force a specific model id if the runtime doesn't emit one.
#name?
optionalname?:string
Defined in: packages/observability/src/cost-guard.ts:89
Observer name for tracing.
#onCost?
optionalonCost?: (info) =>void|Promise<void>
Defined in: packages/observability/src/cost-guard.ts:71
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?
optionalonError?:CostGuardErrorHandler
Defined in: packages/observability/src/cost-guard.ts:83
Isolated sink for internal / callback failures. Never allowed to escape.
#onExceeded?
optionalonExceeded?: (info) =>void|Promise<void>
Defined in: packages/observability/src/cost-guard.ts:81
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?
optionalprices?:Record<string,TokenPrice>
Defined in: packages/observability/src/cost-guard.ts:66
Optional price table override. Partial β merged over DEFAULT_PRICES.
#store?
optionalstore?:CostStore
Defined in: packages/observability/src/cost-guard-store.ts:12
Durable store that receives every priced call. With it, the budget is checked against spend recorded by all instances in the store's current window; without it, totals live in process memory (development only; warns in production).
#Inherited from
#tenant?
optionaltenant?:string
Defined in: packages/observability/src/cost-guard.ts:55
Tenant the spend is recorded under in store. Default 'default'.
#unknownModelPolicy?
optionalunknownModelPolicy?:UnknownModelPolicy
Defined in: packages/observability/src/cost-guard.ts:87
Unknown models fail closed by default; use allow-zero only for explicitly free/local models.
#warnWithoutStore?
optionalwarnWithoutStore?:boolean
Defined in: packages/observability/src/cost-guard-store.ts:18
Controls the warning for a guard that runs without a store. By default it
warns when NODE_ENV is production, and on Cloudflare Workers when
NODE_ENV is not set. true always warns; false silences it.
#Inherited from
CostGuardStoreOptions.warnWithoutStore
#Interface: CostGuardStoreOptions
Defined in: packages/observability/src/cost-guard-store.ts:6
Durable accounting shared by costGuard, multiTenantCostGuard and createAdvancedCostGuard.
#Extended by
#Properties
#store?
optionalstore?:CostStore
Defined in: packages/observability/src/cost-guard-store.ts:12
Durable store that receives every priced call. With it, the budget is checked against spend recorded by all instances in the store's current window; without it, totals live in process memory (development only; warns in production).
#warnWithoutStore?
optionalwarnWithoutStore?:boolean
Defined in: packages/observability/src/cost-guard-store.ts:18
Controls the warning for a guard that runs without a store. By default it
warns when NODE_ENV is production, and on Cloudflare Workers when
NODE_ENV is not set. true always warns; false silences it.
#Interface: CostReleaseInput
Defined in: packages/observability/src/cost-store.ts:60
Input of CostStore.release.
#Properties
#reservationId
reservationId:
string
Defined in: packages/observability/src/cost-store.ts:62
#tenant
tenant:
string
Defined in: packages/observability/src/cost-store.ts:61
#Interface: CostReserveInput
Defined in: packages/observability/src/cost-store.ts:32
Input of CostStore.reserve.
#Properties
#amountUsd
amountUsd:
number
Defined in: packages/observability/src/cost-store.ts:37
Upper estimate of the spend to hold, in USD.
#capUsd?
optionalcapUsd?:number
Defined in: packages/observability/src/cost-store.ts:39
Tenant cap for the window, in USD. Omit to hold the amount without a ceiling.
#reservationId
reservationId:
string
Defined in: packages/observability/src/cost-store.ts:35
Caller-chosen idempotency key, unique per tenant. Reusing it replays the first outcome.
#tenant
tenant:
string
Defined in: packages/observability/src/cost-store.ts:33
#windowKey?
optionalwindowKey?:string
Defined in: packages/observability/src/cost-store.ts:41
Accounting window. Defaults to the store's current window.
#Interface: CostSample
Defined in: packages/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: packages/observability/src/cost-chargeback.ts:19
ISO 8601 β when the call completed.
#completionTokens
completionTokens:
number
Defined in: packages/observability/src/cost-chargeback.ts:29
#costUsd?
optionalcostUsd?:number
Defined in: packages/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: packages/observability/src/cost-chargeback.ts:27
Model id used for this call.
#promptTokens
promptTokens:
number
Defined in: packages/observability/src/cost-chargeback.ts:28
#skill?
optionalskill?:string
Defined in: packages/observability/src/cost-chargeback.ts:24
Optional skill / tool that drove the call.
#tenant
tenant:
string
Defined in: packages/observability/src/cost-chargeback.ts:20
#tool?
optionaltool?:string
Defined in: packages/observability/src/cost-chargeback.ts:25
#user?
optionaluser?:string
Defined in: packages/observability/src/cost-chargeback.ts:22
Optional acting user id within the tenant.
#Interface: CostSpendRecord
Defined in: packages/observability/src/cost-store.ts:344
Spend that already happened and must be written to a CostStore by an observer.
#Properties
#costUsd
costUsd:
number
Defined in: packages/observability/src/cost-store.ts:346
#tenant
tenant:
string
Defined in: packages/observability/src/cost-store.ts:345
#usage?
optionalusage?: readonlyCostUsageEntry[]
Defined in: packages/observability/src/cost-store.ts:347
#Interface: CostStore
Defined in: packages/observability/src/cost-store.ts:80
Durable, tenant-scoped spend accounting. reserve holds an estimate
atomically against the cap, commit replaces it with the real spend, and
release returns it when the call fails. All three are idempotent per
reservationId: a repeated call returns the current window without counting twice.
With reservationTtlMs, a reservation left unsettled past the TTL is released
by the store itself, so a dropped call stops counting against the cap.
#Extended by
#Properties
#commit
commit: (
input) =>Promise<CostWindow>
Defined in: packages/observability/src/cost-store.ts:82
#Parameters
input
#Returns
Promise<CostWindow>
#release
release: (
input) =>Promise<CostWindow>
Defined in: packages/observability/src/cost-store.ts:83
#Parameters
input
#Returns
Promise<CostWindow>
#reserve
reserve: (
input) =>Promise<CostReserveResult>
Defined in: packages/observability/src/cost-store.ts:81
#Parameters
input
#Returns
Promise<CostReserveResult>
#window
window: (
input) =>Promise<CostWindow>
Defined in: packages/observability/src/cost-store.ts:84
#Parameters
input
#Returns
Promise<CostWindow>
#Interface: CostStoreOptions
Defined in: packages/observability/src/cost-store.ts:88
Options shared by the bundled CostStore implementations.
#Properties
#now?
optionalnow?: () =>Date
Defined in: packages/observability/src/cost-store.ts:92
Clock override for tests.
#Returns
Date
#reservationTtlMs?
optionalreservationTtlMs?:number
Defined in: packages/observability/src/cost-store.ts:99
Age in ms after which a reservation that was neither committed nor released
expires: it stops counting against the cap and is settled as released, so a
later commit throws AK_COST_RESERVATION_RELEASED. Checked on every store
call, no scheduled job needed. Set it above your slowest call. Default: never.
#windowKey?
optionalwindowKey?: (now) =>string
Defined in: packages/observability/src/cost-store.ts:90
Maps the current time to an accounting window. Defaults to the UTC month (2026-10).
#Parameters
now
Date
#Returns
string
#Interface: CostUsageEntry
Defined in: packages/observability/src/cost-store.ts:4
One priced model call, written to the usage ledger when a reservation is committed.
#Extended by
#Properties
#completionTokens
completionTokens:
number
Defined in: packages/observability/src/cost-store.ts:7
#costUsd
costUsd:
number
Defined in: packages/observability/src/cost-store.ts:8
#fallback?
optionalfallback?:boolean
Defined in: packages/observability/src/cost-store.ts:12
True when the call ran on a fallback model.
#model
model:
string
Defined in: packages/observability/src/cost-store.ts:5
#promptTokens
promptTokens:
number
Defined in: packages/observability/src/cost-store.ts:6
#source?
optionalsource?:string
Defined in: packages/observability/src/cost-store.ts:10
Free-form origin of the call ('chat', 'extraction', a route name).
#Interface: CostWindow
Defined in: packages/observability/src/cost-store.ts:16
Durable spend state of one tenant in one accounting window.
#Properties
#capUsd?
optionalcapUsd?:number
Defined in: packages/observability/src/cost-store.ts:24
Cap this window was evaluated against, when one was supplied.
#remainingUsd?
optionalremainingUsd?:number
Defined in: packages/observability/src/cost-store.ts:26
capUsd - spentUsd - reservedUsd, never negative.
#reservedUsd
reservedUsd:
number
Defined in: packages/observability/src/cost-store.ts:22
Reserved, not yet committed or released, in USD.
#spentUsd
spentUsd:
number
Defined in: packages/observability/src/cost-store.ts:20
Committed spend in USD.
#tenant
tenant:
string
Defined in: packages/observability/src/cost-store.ts:17
#utilization?
optionalutilization?:number
Defined in: packages/observability/src/cost-store.ts:28
(spentUsd + reservedUsd) / capUsd, always finite.
#windowKey
windowKey:
string
Defined in: packages/observability/src/cost-store.ts:18
#Interface: CostWindowInput
Defined in: packages/observability/src/cost-store.ts:66
Input of CostStore.window.
#Properties
#capUsd?
optionalcapUsd?:number
Defined in: packages/observability/src/cost-store.ts:68
#tenant
tenant:
string
Defined in: packages/observability/src/cost-store.ts:67
#windowKey?
optionalwindowKey?:string
Defined in: packages/observability/src/cost-store.ts:69
#Interface: DatadogSinkConfig
Defined in: packages/observability/src/datadog.ts:10
Datadog API key, site, service tags, and batch settings.
#Extends
#Properties
#apiKey
apiKey:
string
Defined in: packages/observability/src/datadog.ts:11
#batchSize?
optionalbatchSize?:number
Defined in: packages/observability/src/http-batch-sink.ts:14
Max events per POST. Default 25. Positive integer.
#Inherited from
#env?
optionalenv?:string
Defined in: packages/observability/src/datadog.ts:17
Environment tag (prod, staging, ...).
#fetch?
optionalfetch?: {(input,init?):Promise<Response>; (input,init?):Promise<Response>; }
Defined in: packages/observability/src/http-batch-sink.ts:27
#Call Signature
(
input,init?):Promise<Response>
Parameters
input
RequestInfo | URL
init?
RequestInit
Returns
Promise<Response>
#Call Signature
(
input,init?):Promise<Response>
Parameters
input
string | Request | URL
init?
RequestInit
Returns
Promise<Response>
#Inherited from
#flushIntervalMs?
optionalflushIntervalMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:18
Periodic drain interval (ms). Default 2000. Finite > 0.
#Inherited from
HttpBatchOptions.flushIntervalMs
#maxQueueSize?
optionalmaxQueueSize?:number
Defined in: packages/observability/src/http-batch-sink.ts:16
Hard queue cap; drop oldest when full. Default 1000. Positive integer.
#Inherited from
#maxRetries?
optionalmaxRetries?:number
Defined in: packages/observability/src/http-batch-sink.ts:20
Retries after the initial attempt. Default 3. Integer β₯ 0.
#Inherited from
#onError?
optionalonError?: (error) =>void|Promise<void>
Defined in: packages/observability/src/http-batch-sink.ts:26
Isolated error sink; throws/rejections never escape the observer.
#Parameters
error
unknown
#Returns
void | Promise<void>
#Inherited from
#requestTimeoutMs?
optionalrequestTimeoutMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:24
Per-request timeout (ms). Default 10000. Positive integer.
#Inherited from
HttpBatchOptions.requestTimeoutMs
#retryBaseDelayMs?
optionalretryBaseDelayMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:22
Base delay (ms); full-jitter exponential retries capped at 30s; valid Retry-After is honored as a minimum, also capped. Default 100.
#Inherited from
HttpBatchOptions.retryBaseDelayMs
#service?
optionalservice?:string
Defined in: packages/observability/src/datadog.ts:15
Service name attached to every event.
#site?
optionalsite?:string
Defined in: packages/observability/src/datadog.ts:13
Datadog site, defaults to datadoghq.com (US1). Use datadoghq.eu, us5.datadoghq.com, etc.
#Interface: DevtoolsClient
Defined in: packages/observability/src/devtools.ts:5
Transport endpoint that receives devtools envelopes.
#Properties
#close?
optionalclose?: () =>void
Defined in: packages/observability/src/devtools.ts:8
#Returns
void
#id
id:
string
Defined in: packages/observability/src/devtools.ts:6
#send
send: (
event) =>void
Defined in: packages/observability/src/devtools.ts:7
#Parameters
event
#Returns
void
#Interface: DevtoolsServer
Defined in: packages/observability/src/devtools.ts:26
Observer, transport hooks, and retained event buffer returned by the hub.
#Properties
#attach
attach: (
client) => () =>void
Defined in: packages/observability/src/devtools.ts:32
Attach a transport β SSE response, WS connection, in-process sink.
#Parameters
client
#Returns
() => void
#buffer
buffer: () => readonly
object[]
Defined in: packages/observability/src/devtools.ts:36
Snapshot of retained events, newest last.
#Returns
readonly object[]
#close
close: () =>
void
Defined in: packages/observability/src/devtools.ts:34
Drop all clients and clear buffer.
#Returns
void
#observer
observer:
Observer
Defined in: packages/observability/src/devtools.ts:28
Observer you can plug into createRuntime(\{ observers: [...] \}).
#publish
publish: (
event) =>void
Defined in: packages/observability/src/devtools.ts:30
Push arbitrary events (tests / custom sources).
#Parameters
event
AgentEvent
#Returns
void
#Interface: DevtoolsServerOptions
Defined in: packages/observability/src/devtools.ts:18
Buffer and server identity settings for the in-process devtools hub.
#Properties
#bufferSize?
optionalbufferSize?:number
Defined in: packages/observability/src/devtools.ts:20
Max events to retain in the ring buffer. Default 500.
#serverId?
optionalserverId?:string
Defined in: packages/observability/src/devtools.ts:22
Server id emitted in the hello envelope. Default: random.
#Interface: FileTraceSink
Defined in: packages/observability/src/trace-viewer.ts:98
Span collector with a disk flush operation that writes JSON and optional HTML.
#Properties
#flush
flush: (
options?) =>Promise<{html?:string;json:string; }>
Defined in: packages/observability/src/trace-viewer.ts:105
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: packages/observability/src/trace-viewer.ts:101
#Parameters
span
#Returns
void
#onSpanStart
onSpanStart: (
span) =>void
Defined in: packages/observability/src/trace-viewer.ts:100
Observer-compatible span callbacks. Plug into createTraceTracker.
#Parameters
span
#Returns
void
#spans
spans: () =>
TraceSpan[]
Defined in: packages/observability/src/trace-viewer.ts:103
Snapshot of spans recorded so far.
#Returns
#Interface: HttpBatchOptions
Defined in: packages/observability/src/http-batch-sink.ts:12
Common batching / retry knobs for the three HTTP log sinks.
#Extended by
#Properties
#batchSize?
optionalbatchSize?:number
Defined in: packages/observability/src/http-batch-sink.ts:14
Max events per POST. Default 25. Positive integer.
#fetch?
optionalfetch?: {(input,init?):Promise<Response>; (input,init?):Promise<Response>; }
Defined in: packages/observability/src/http-batch-sink.ts:27
#Call Signature
(
input,init?):Promise<Response>
Parameters
input
RequestInfo | URL
init?
RequestInit
Returns
Promise<Response>
#Call Signature
(
input,init?):Promise<Response>
Parameters
input
string | Request | URL
init?
RequestInit
Returns
Promise<Response>
#flushIntervalMs?
optionalflushIntervalMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:18
Periodic drain interval (ms). Default 2000. Finite > 0.
#maxQueueSize?
optionalmaxQueueSize?:number
Defined in: packages/observability/src/http-batch-sink.ts:16
Hard queue cap; drop oldest when full. Default 1000. Positive integer.
#maxRetries?
optionalmaxRetries?:number
Defined in: packages/observability/src/http-batch-sink.ts:20
Retries after the initial attempt. Default 3. Integer β₯ 0.
#onError?
optionalonError?: (error) =>void|Promise<void>
Defined in: packages/observability/src/http-batch-sink.ts:26
Isolated error sink; throws/rejections never escape the observer.
#Parameters
error
unknown
#Returns
void | Promise<void>
#requestTimeoutMs?
optionalrequestTimeoutMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:24
Per-request timeout (ms). Default 10000. Positive integer.
#retryBaseDelayMs?
optionalretryBaseDelayMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:22
Base delay (ms); full-jitter exponential retries capped at 30s; valid Retry-After is honored as a minimum, also capped. Default 100.
#Interface: InMemoryCostStore
Defined in: packages/observability/src/cost-store.ts:237
CostStore plus the ledger rows written by commit, for assertions in tests.
#Extends
#Properties
#commit
commit: (
input) =>Promise<CostWindow>
Defined in: packages/observability/src/cost-store.ts:82
#Parameters
input
#Returns
Promise<CostWindow>
#Inherited from
#ledger
ledger: () =>
InMemoryLedgerRow[]
Defined in: packages/observability/src/cost-store.ts:238
#Returns
#release
release: (
input) =>Promise<CostWindow>
Defined in: packages/observability/src/cost-store.ts:83
#Parameters
input
#Returns
Promise<CostWindow>
#Inherited from
#reserve
reserve: (
input) =>Promise<CostReserveResult>
Defined in: packages/observability/src/cost-store.ts:81
#Parameters
input
#Returns
Promise<CostReserveResult>
#Inherited from
#window
window: (
input) =>Promise<CostWindow>
Defined in: packages/observability/src/cost-store.ts:84
#Parameters
input
#Returns
Promise<CostWindow>
#Inherited from
#Interface: InMemoryLedgerRow
Defined in: packages/observability/src/cost-store.ts:231
A ledger row as kept by createInMemoryCostStore.
#Extends
#Properties
#completionTokens
completionTokens:
number
Defined in: packages/observability/src/cost-store.ts:7
#Inherited from
CostUsageEntry.completionTokens
#costUsd
costUsd:
number
Defined in: packages/observability/src/cost-store.ts:8
#Inherited from
#fallback?
optionalfallback?:boolean
Defined in: packages/observability/src/cost-store.ts:12
True when the call ran on a fallback model.
#Inherited from
#model
model:
string
Defined in: packages/observability/src/cost-store.ts:5
#Inherited from
#promptTokens
promptTokens:
number
Defined in: packages/observability/src/cost-store.ts:6
#Inherited from
#reservationId
reservationId:
string
Defined in: packages/observability/src/cost-store.ts:233
#source?
optionalsource?:string
Defined in: packages/observability/src/cost-store.ts:10
Free-form origin of the call ('chat', 'extraction', a route name).
#Inherited from
#tenant
tenant:
string
Defined in: packages/observability/src/cost-store.ts:232
#Interface: LangSmithConfig
Defined in: packages/observability/src/langsmith.ts:6
API key, project, endpoint, and isolated error callback for LangSmith.
#Properties
#apiKey
apiKey:
string
Defined in: packages/observability/src/langsmith.ts:7
#endpoint?
optionalendpoint?:string
Defined in: packages/observability/src/langsmith.ts:9
#onError?
optionalonError?: (error) =>void|Promise<void>
Defined in: packages/observability/src/langsmith.ts:11
Isolated error sink; throws/rejections never escape the observer.
#Parameters
error
unknown
#Returns
void | Promise<void>
#projectName?
optionalprojectName?:string
Defined in: packages/observability/src/langsmith.ts:8
#Interface: LangSmithObserver
Defined in: packages/observability/src/langsmith.ts:15
LangSmith observer with explicit batch flushing and shutdown lifecycle.
#Extends
Observer
#Properties
#name
name:
string
Defined in: packages/core/dist/chat-C1aW2_Tp.d.ts:131
#Inherited from
Observer.name
#on
on: (
event) =>void|Promise<void>
Defined in: packages/core/dist/chat-C1aW2_Tp.d.ts:132
#Parameters
event
AgentEvent
#Returns
void | Promise<void>
#Inherited from
Observer.on
#Methods
#flush()
flush():
Promise<void>
Defined in: packages/observability/src/langsmith.ts:16
#Returns
Promise<void>
#shutdown()
shutdown():
Promise<void>
Defined in: packages/observability/src/langsmith.ts:17
#Returns
Promise<void>
#Interface: LifecycleObserver
Defined in: packages/observability/src/http-batch-sink.ts:6
Shared lifecycle surface for HTTP sinks and SDK bridges.
#Extends
Observer
#Properties
#name
name:
string
Defined in: packages/core/dist/chat-C1aW2_Tp.d.ts:131
#Inherited from
Observer.name
#on
on: (
event) =>void|Promise<void>
Defined in: packages/core/dist/chat-C1aW2_Tp.d.ts:132
#Parameters
event
AgentEvent
#Returns
void | Promise<void>
#Inherited from
Observer.on
#Methods
#flush()
flush():
Promise<void>
Defined in: packages/observability/src/http-batch-sink.ts:7
#Returns
Promise<void>
#shutdown()
shutdown():
Promise<void>
Defined in: packages/observability/src/http-batch-sink.ts:8
#Returns
Promise<void>
#Interface: MultiTenantCostGuardOptions
Defined in: packages/observability/src/cost-guard-multi-tenant.ts:17
Per-tenant budgets, pricing, tenant resolver, and isolated callbacks.
#Extends
#Properties
#budgets
budgets:
Record<string,number>
Defined in: packages/observability/src/cost-guard-multi-tenant.ts:22
Per-tenant USD budgets. Tenants not listed here either inherit
defaultBudgetUsd (if set) or are unmetered (no enforcement).
#defaultBudgetUsd?
optionaldefaultBudgetUsd?:number
Defined in: packages/observability/src/cost-guard-multi-tenant.ts:27
Fallback budget for tenants not explicitly listed in budgets.
Omit to make unlisted tenants unmetered.
#modelOverride?
optionalmodelOverride?:string
Defined in: packages/observability/src/cost-guard-multi-tenant.ts:64
#name?
optionalname?:string
Defined in: packages/observability/src/cost-guard-multi-tenant.ts:66
#onCost?
optionalonCost?: (info) =>void|Promise<void>
Defined in: packages/observability/src/cost-guard-multi-tenant.ts:54
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?
optionalonError?:CostGuardErrorHandler
Defined in: packages/observability/src/cost-guard-multi-tenant.ts:63
Isolated sink for internal / callback failures.
#onExceeded?
optionalonExceeded?: (info) =>void|Promise<void>
Defined in: packages/observability/src/cost-guard-multi-tenant.ts:48
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?
optionalprices?:Record<string,TokenPrice>
Defined in: packages/observability/src/cost-guard-multi-tenant.ts:40
Optional price table override.
#store?
optionalstore?:CostStore
Defined in: packages/observability/src/cost-guard-store.ts:12
Durable store that receives every priced call. With it, the budget is checked against spend recorded by all instances in the store's current window; without it, totals live in process memory (development only; warns in production).
#Inherited from
#tenantOf?
optionaltenantOf?: () =>string|undefined
Defined in: packages/observability/src/cost-guard-multi-tenant.ts:38
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?
optionalunknownModelPolicy?:"error"|"allow-zero"
Defined in: packages/observability/src/cost-guard-multi-tenant.ts:65
#warnWithoutStore?
optionalwarnWithoutStore?:boolean
Defined in: packages/observability/src/cost-guard-store.ts:18
Controls the warning for a guard that runs without a store. By default it
warns when NODE_ENV is production, and on Cloudflare Workers when
NODE_ENV is not set. true always warns; false silences it.
#Inherited from
CostGuardStoreOptions.warnWithoutStore
#Interface: NewRelicSinkConfig
Defined in: packages/observability/src/new-relic.ts:10
New Relic API key, region, service label, and batch settings.
#Extends
#Properties
#apiKey
apiKey:
string
Defined in: packages/observability/src/new-relic.ts:12
New Relic license / API key (NRAK-... or license key).
#batchSize?
optionalbatchSize?:number
Defined in: packages/observability/src/http-batch-sink.ts:14
Max events per POST. Default 25. Positive integer.
#Inherited from
#fetch?
optionalfetch?: {(input,init?):Promise<Response>; (input,init?):Promise<Response>; }
Defined in: packages/observability/src/http-batch-sink.ts:27
#Call Signature
(
input,init?):Promise<Response>
Parameters
input
RequestInfo | URL
init?
RequestInit
Returns
Promise<Response>
#Call Signature
(
input,init?):Promise<Response>
Parameters
input
string | Request | URL
init?
RequestInit
Returns
Promise<Response>
#Inherited from
#flushIntervalMs?
optionalflushIntervalMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:18
Periodic drain interval (ms). Default 2000. Finite > 0.
#Inherited from
HttpBatchOptions.flushIntervalMs
#maxQueueSize?
optionalmaxQueueSize?:number
Defined in: packages/observability/src/http-batch-sink.ts:16
Hard queue cap; drop oldest when full. Default 1000. Positive integer.
#Inherited from
#maxRetries?
optionalmaxRetries?:number
Defined in: packages/observability/src/http-batch-sink.ts:20
Retries after the initial attempt. Default 3. Integer β₯ 0.
#Inherited from
#onError?
optionalonError?: (error) =>void|Promise<void>
Defined in: packages/observability/src/http-batch-sink.ts:26
Isolated error sink; throws/rejections never escape the observer.
#Parameters
error
unknown
#Returns
void | Promise<void>
#Inherited from
#region?
optionalregion?:"US"|"EU"
Defined in: packages/observability/src/new-relic.ts:14
Region. 'US' (default) β log-api.newrelic.com, 'EU' β log-api.eu.newrelic.com.
#requestTimeoutMs?
optionalrequestTimeoutMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:24
Per-request timeout (ms). Default 10000. Positive integer.
#Inherited from
HttpBatchOptions.requestTimeoutMs
#retryBaseDelayMs?
optionalretryBaseDelayMs?:number
Defined in: packages/observability/src/http-batch-sink.ts:22
Base delay (ms); full-jitter exponential retries capped at 30s; valid Retry-After is honored as a minimum, also capped. Default 100.
#Inherited from
HttpBatchOptions.retryBaseDelayMs
#service?
optionalservice?:string
Defined in: packages/observability/src/new-relic.ts:16
Service name attached to every event.
#Interface: ObserverRedactionOptions
Defined in: packages/observability/src/redaction.ts:30
Rules, mode, vault, roles, and audit sink used to sanitize observer events.
#Properties
#allowedRoles?
optionalallowedRoles?:string[]
Defined in: packages/observability/src/redaction.ts:39
#audit?
optionalaudit?:RedactionAuditSink
Defined in: packages/observability/src/redaction.ts:40
#mode?
optionalmode?:ObserverRedactionMode
Defined in: packages/observability/src/redaction.ts:37
#rules
rules:
PIIRule[]
Defined in: packages/observability/src/redaction.ts:36
Rules to apply. Pass DEFAULT_PII_RULES for the baseline set,
compilePIITaxonomy(json) for a custom JSON taxonomy, or any
hand-rolled PIIRule[].
#vault?
optionalvault?:RedactionVault
Defined in: packages/observability/src/redaction.ts:38
#Interface: OpenTelemetryConfig
Defined in: packages/observability/src/opentelemetry.ts:6
OTLP endpoint, service name, and isolated error callback.
#Properties
#endpoint?
optionalendpoint?:string
Defined in: packages/observability/src/opentelemetry.ts:7
#onError?
optionalonError?: (error) =>void|Promise<void>
Defined in: packages/observability/src/opentelemetry.ts:10
Isolated error sink; throws/rejections never escape the observer.
#Parameters
error
unknown
#Returns
void | Promise<void>
#serviceName?
optionalserviceName?:string
Defined in: packages/observability/src/opentelemetry.ts:8
#Interface: OpenTelemetryObserver
Defined in: packages/observability/src/opentelemetry.ts:14
OpenTelemetry observer with explicit flush and shutdown lifecycle.
#Extends
Observer
#Properties
#name
name:
string
Defined in: packages/core/dist/chat-C1aW2_Tp.d.ts:131
#Inherited from
Observer.name
#on
on: (
event) =>void|Promise<void>
Defined in: packages/core/dist/chat-C1aW2_Tp.d.ts:132
#Parameters
event
AgentEvent
#Returns
void | Promise<void>
#Inherited from
Observer.on
#Methods
#flush()
flush():
Promise<void>
Defined in: packages/observability/src/opentelemetry.ts:15
#Returns
Promise<void>
#shutdown()
shutdown():
Promise<void>
Defined in: packages/observability/src/opentelemetry.ts:16
#Returns
Promise<void>
#Interface: PiiAuditInput
Defined in: packages/observability/src/audit-log.ts:61
PII scan details converted to signed audit records.
#Properties
#action
action:
PiiAuditAction
Defined in: packages/observability/src/audit-log.ts:63
#actor
actor:
string
Defined in: packages/observability/src/audit-log.ts:62
#hits
hits: readonly
PIIRedactionHit[]
Defined in: packages/observability/src/audit-log.ts:65
#reason?
optionalreason?:string
Defined in: packages/observability/src/audit-log.ts:66
#subjectId?
optionalsubjectId?:string
Defined in: packages/observability/src/audit-log.ts:64
#Interface: PiiAuditPayload
Defined in: packages/observability/src/audit-log.ts:70
PII match metadata stored in an audit record without matched text.
#Properties
#count
count:
number
Defined in: packages/observability/src/audit-log.ts:73
#matches
matches:
object[]
Defined in: packages/observability/src/audit-log.ts:74
#length
length:
number
#offset
offset:
number
#reason?
optionalreason?:string
Defined in: packages/observability/src/audit-log.ts:75
#rule
rule:
string
Defined in: packages/observability/src/audit-log.ts:72
#subjectId?
optionalsubjectId?:string
Defined in: packages/observability/src/audit-log.ts:71
#Interface: ProviderTokenCounterOptions
Defined in: packages/observability/src/token-counter.ts:125
Options for creating a provider-specific token counter.
#Properties
#name
name:
string
Defined in: packages/observability/src/token-counter.ts:143
Human-readable name for this counter.
#perMessageOverhead?
optionalperMessageOverhead?:number
Defined in: packages/observability/src/token-counter.ts:145
Per-message overhead in tokens. Defaults to 4.
#tokenize
tokenize: (
text,model?) => readonlyunknown[] |Promise<readonlyunknown[]>
Defined in: packages/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: packages/observability/src/prod-control.ts:21
Captured paused state, retained events, and pending tool overrides for a run.
#Properties
#capturedAt
capturedAt:
string
Defined in: packages/observability/src/prod-control.ts:24
ISO timestamp.
#events
events:
AgentEvent[]
Defined in: packages/observability/src/prod-control.ts:29
Verbatim recent events for the run (capped).
#metadata?
optionalmetadata?:Record<string,unknown>
Defined in: packages/observability/src/prod-control.ts:33
Free-form metadata you want to ship with the support ticket.
#overrides
overrides:
ToolOverride[]
Defined in: packages/observability/src/prod-control.ts:31
Pending tool overrides.
#paused
paused:
boolean
Defined in: packages/observability/src/prod-control.ts:25
#runId
runId:
string
Defined in: packages/observability/src/prod-control.ts:22
#seq
seq:
number
Defined in: packages/observability/src/prod-control.ts:27
Last seq number observed for the run.
#Interface: SignedAuditLog
Defined in: packages/observability/src/audit-log.ts:51
Operations exposed by a signed hash-chained audit log.
#Properties
#append
append: <
TPayload>(input) =>Promise<AuditEntry<TPayload>>
Defined in: packages/observability/src/audit-log.ts:52
#Type Parameters
TPayload
TPayload
#Parameters
input
AppendAuditInput<TPayload>
#Returns
Promise<AuditEntry<TPayload>>
#list
list: () =>
Promise<AuditEntry<unknown>[]>
Defined in: packages/observability/src/audit-log.ts:54
#Returns
Promise<AuditEntry<unknown>[]>
#verify
verify: () =>
Promise<AuditVerifyResult>
Defined in: packages/observability/src/audit-log.ts:53
#Returns
Promise<AuditVerifyResult>
#Interface: SloObserver
Defined in: packages/observability/src/slo.ts:89
Observer with metric snapshots, exporters, and timer cleanup.
#Extends
Observer
#Properties
#name
name:
string
Defined in: packages/core/dist/chat-C1aW2_Tp.d.ts:131
#Inherited from
Observer.name
#on
on: (
event) =>void|Promise<void>
Defined in: packages/core/dist/chat-C1aW2_Tp.d.ts:132
#Parameters
event
AgentEvent
#Returns
void | Promise<void>
#Inherited from
Observer.on
#otel
otel: () =>
object[]
Defined in: packages/observability/src/slo.ts:94
OpenTelemetry-shaped metric records (push to OTLP).
#Returns
object[]
#prometheus
prometheus: () =>
string
Defined in: packages/observability/src/slo.ts:92
Prometheus exposition text (# HELP / # TYPE / metric\{...\} value).
#Returns
string
#snapshot
snapshot: (
windowMs?) =>SloSnapshot
Defined in: packages/observability/src/slo.ts:90
#Parameters
windowMs?
number
#Returns
#stop
stop: () =>
void
Defined in: packages/observability/src/slo.ts:96
Stop the burn-rate timer.
#Returns
void
#Interface: SloOptions
Defined in: packages/observability/src/slo.ts:37
Target, stall threshold, burn windows, alert sink, and clock for an SLO observer.
#Properties
#alert?
optionalalert?:CostAlertSink
Defined in: packages/observability/src/slo.ts:44
Alert sink. Same contract as cost-guard alerts so a single sink can fan-in.
#burnRateWindowsMs?
optionalburnRateWindowsMs?:number[]
Defined in: packages/observability/src/slo.ts:42
Burn-rate windows. Default [3_600_000, 21_600_000] (1h, 6h).
#now?
optionalnow?: () =>number
Defined in: packages/observability/src/slo.ts:46
Wall clock β overridable for tests.
#Returns
number
#stallThresholdMs?
optionalstallThresholdMs?:number
Defined in: packages/observability/src/slo.ts:40
First-token latency above this counts as a stall. Default 8000ms.
#targets?
optionaltargets?:SloTargets
Defined in: packages/observability/src/slo.ts:38
#Interface: SloSnapshot
Defined in: packages/observability/src/slo.ts:77
Aggregated rates and latency quantiles for a time window.
#Properties
#latencyP50Ms
latencyP50Ms:
number
Defined in: packages/observability/src/slo.ts:81
#latencyP95Ms
latencyP95Ms:
number
Defined in: packages/observability/src/slo.ts:82
#latencyP99Ms
latencyP99Ms:
number
Defined in: packages/observability/src/slo.ts:83
#streamingStallRate
streamingStallRate:
number
Defined in: packages/observability/src/slo.ts:85
#successRate
successRate:
number
Defined in: packages/observability/src/slo.ts:80
#toolErrorRate
toolErrorRate:
number
Defined in: packages/observability/src/slo.ts:84
#total
total:
number
Defined in: packages/observability/src/slo.ts:79
#windowMs
windowMs:
number
Defined in: packages/observability/src/slo.ts:78
#Interface: SloTargets
Defined in: packages/observability/src/slo.ts:25
Target rates and latency used to evaluate the SLO snapshot.
#Properties
#latencyP95Ms?
optionallatencyP95Ms?:number
Defined in: packages/observability/src/slo.ts:29
Milliseconds. Default 5000.
#streamingStallRate?
optionalstreamingStallRate?:number
Defined in: packages/observability/src/slo.ts:33
0β1. Default 0.005.
#successRate?
optionalsuccessRate?:number
Defined in: packages/observability/src/slo.ts:27
0β1. Default 0.99.
#toolErrorRate?
optionaltoolErrorRate?:number
Defined in: packages/observability/src/slo.ts:31
0β1. Default 0.01.
#Interface: TokenPrice
Defined in: packages/observability/src/cost-guard.ts:7
Dollar cost per 1K tokens for input and output.
#Properties
#input
input:
number
Defined in: packages/observability/src/cost-guard.ts:8
#output
output:
number
Defined in: packages/observability/src/cost-guard.ts:9
#Interface: ToolOverride
Defined in: packages/observability/src/prod-control.ts:5
Auth-gated, transport-agnostic controls for pausing runs, overriding tools, and capturing or restoring snapshots.
#Properties
#reason?
optionalreason?:string
Defined in: packages/observability/src/prod-control.ts:17
Audit note included in the snapshot + audit log.
#result
result:
string
Defined in: packages/observability/src/prod-control.ts:13
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?
optionalstatus?:"error"|"complete"
Defined in: packages/observability/src/prod-control.ts:15
Optional: also mark the call status. Defaults to 'complete'.
#tool
tool:
string
Defined in: packages/observability/src/prod-control.ts:7
Tool to override on the next call.
#Interface: TopologyEdge
Defined in: packages/observability/src/topology-graph.ts:42
Directed communication edge between agents in a topology graph.
#Properties
#count
count:
number
Defined in: packages/observability/src/topology-graph.ts:48
Number of times this edge fired.
#from
from:
string
Defined in: packages/observability/src/topology-graph.ts:45
#id
id:
string
Defined in: packages/observability/src/topology-graph.ts:44
fromβto (stable id).
#lastResult?
optionallastResult?:string
Defined in: packages/observability/src/topology-graph.ts:51
#lastTask?
optionallastTask?:string
Defined in: packages/observability/src/topology-graph.ts:50
Most recent task/result snippet (trimmed) β useful for tooltips.
#to
to:
string
Defined in: packages/observability/src/topology-graph.ts:46
#Interface: TopologyGraph
Defined in: packages/observability/src/topology-graph.ts:55
Mutable topology graph with serializers and change subscriptions.
#Properties
#edges
edges:
Map<string,TopologyEdge>
Defined in: packages/observability/src/topology-graph.ts:57
#ingest
ingest: (
event) =>void
Defined in: packages/observability/src/topology-graph.ts:62
Send a TopologyLogEvent into the graph. Mutates state. Calls every subscriber after each event.
#Parameters
event
#Returns
void
#nodes
nodes:
Map<string,TopologyNode>
Defined in: packages/observability/src/topology-graph.ts:56
#reset
reset: () =>
void
Defined in: packages/observability/src/topology-graph.ts:72
Reset to empty (e.g. when a new run starts).
#Returns
void
#subscribe
subscribe: (
handler) => () =>void
Defined in: packages/observability/src/topology-graph.ts:70
Subscribe to graph changes. Returns an unsubscribe handle.
#Parameters
handler
(snapshot) => void
#Returns
() => void
#toAscii
toAscii: () =>
string
Defined in: packages/observability/src/topology-graph.ts:68
ASCII renderer (Ink-friendly).
#Returns
string
#toJSON
toJSON: () =>
TopologyGraphSnapshot
Defined in: packages/observability/src/topology-graph.ts:64
Snapshot in a JSON-serialisable form for the devtools wire.
#Returns
#toMermaid
toMermaid: () =>
string
Defined in: packages/observability/src/topology-graph.ts:66
Mermaid graph LR diagram.
#Returns
string
#Interface: TopologyGraphOptions
Defined in: packages/observability/src/topology-graph.ts:84
Snippet length and clock overrides for topology graph creation.
#Properties
#now?
optionalnow?: () =>number
Defined in: packages/observability/src/topology-graph.ts:88
Wall clock β overridable for tests.
#Returns
number
#snippetLength?
optionalsnippetLength?:number
Defined in: packages/observability/src/topology-graph.ts:86
Truncation length for task/result tooltips. Default 80.
#Interface: TopologyGraphSnapshot
Defined in: packages/observability/src/topology-graph.ts:76
JSON-serializable node and edge snapshot with update time.
#Properties
#edges
edges:
TopologyEdge[]
Defined in: packages/observability/src/topology-graph.ts:78
#nodes
nodes:
TopologyNode[]
Defined in: packages/observability/src/topology-graph.ts:77
#updatedAt
updatedAt:
string
Defined in: packages/observability/src/topology-graph.ts:80
ISO timestamp of the latest event.
#Interface: TopologyLogEvent
Defined in: packages/observability/src/topology-graph.ts:2
Runtime topology event mirrored here to avoid an observability-to-runtime dependency cycle.
#Properties
#agent?
optionalagent?:string
Defined in: packages/observability/src/topology-graph.ts:5
#iteration?
optionaliteration?:number
Defined in: packages/observability/src/topology-graph.ts:8
#phase
phase:
"dispatch"|"agent:start"|"agent:end"|"merge"|"done"
Defined in: packages/observability/src/topology-graph.ts:4
#result?
optionalresult?:string
Defined in: packages/observability/src/topology-graph.ts:7
#task?
optionaltask?:string
Defined in: packages/observability/src/topology-graph.ts:6
#topology
topology:
string
Defined in: packages/observability/src/topology-graph.ts:3
#Interface: TopologyNode
Defined in: packages/observability/src/topology-graph.ts:27
Agent node and activity counters in a topology graph.
#Properties
#endCount
endCount:
number
Defined in: packages/observability/src/topology-graph.ts:35
#errorCount
errorCount:
number
Defined in: packages/observability/src/topology-graph.ts:36
#id
id:
string
Defined in: packages/observability/src/topology-graph.ts:28
#label
label:
string
Defined in: packages/observability/src/topology-graph.ts:30
Display label. Defaults to the agent id.
#lastActiveAt
lastActiveAt:
number
Defined in: packages/observability/src/topology-graph.ts:38
Last activity timestamp (ms since epoch).
#startCount
startCount:
number
Defined in: packages/observability/src/topology-graph.ts:34
Activity counters useful for sizing/colouring nodes in a viz.
#topology
topology:
string
Defined in: packages/observability/src/topology-graph.ts:32
'supervisor' | 'swarm' | 'hierarchical' | 'blackboard'.
#Interface: TraceReport
Defined in: packages/observability/src/trace-viewer.ts:5
Summary metrics and spans for one trace, used by JSON and HTML exporters.
#Properties
#durationMs
durationMs:
number
Defined in: packages/observability/src/trace-viewer.ts:9
#endTime
endTime:
number
Defined in: packages/observability/src/trace-viewer.ts:8
#errorCount
errorCount:
number
Defined in: packages/observability/src/trace-viewer.ts:11
#spanCount
spanCount:
number
Defined in: packages/observability/src/trace-viewer.ts:10
#spans
spans:
TraceSpan[]
Defined in: packages/observability/src/trace-viewer.ts:12
#startTime
startTime:
number
Defined in: packages/observability/src/trace-viewer.ts:7
#traceId
traceId:
string
Defined in: packages/observability/src/trace-viewer.ts:6
#Interface: TraceSpan
Defined in: packages/observability/src/trace-tracker.ts:15
Span identity, timing, attributes, and completion status produced by the tracker.
#Properties
#attributes
attributes:
Record<string,unknown>
Defined in: packages/observability/src/trace-tracker.ts:21
#endTime?
optionalendTime?:number
Defined in: packages/observability/src/trace-tracker.ts:20
#id
id:
string
Defined in: packages/observability/src/trace-tracker.ts:16
#name
name:
string
Defined in: packages/observability/src/trace-tracker.ts:17
#parentId
parentId:
string|null
Defined in: packages/observability/src/trace-tracker.ts:18
#startTime
startTime:
number
Defined in: packages/observability/src/trace-tracker.ts:19
#status
status:
"ok"|"error"
Defined in: packages/observability/src/trace-tracker.ts:22
#Interface: TraceTrackerCallbacks
Defined in: packages/observability/src/trace-tracker.ts:26
Callbacks invoked when the tracker starts or completes a span.
#Properties
#onSpanEnd
onSpanEnd: (
span) =>void
Defined in: packages/observability/src/trace-tracker.ts:28
#Parameters
span
#Returns
void
#onSpanStart
onSpanStart: (
span) =>void
Defined in: packages/observability/src/trace-tracker.ts:27
#Parameters
span
#Returns
void
#Interface: WebhookAlertSinkOptions
Defined in: packages/observability/src/cost-guard-alert-sinks.ts:25
HTTP and retry settings for webhookAlertSink.
#Properties
#fetch?
optionalfetch?: {(input,init?):Promise<Response>; (input,init?):Promise<Response>; }
Defined in: packages/observability/src/cost-guard-alert-sinks.ts:28
Override fetch (tests / custom clients).
#Call Signature
(
input,init?):Promise<Response>
Parameters
input
RequestInfo | URL
init?
RequestInit
Returns
Promise<Response>
#Call Signature
(
input,init?):Promise<Response>
Parameters
input
string | Request | URL
init?
RequestInit
Returns
Promise<Response>
#headers?
optionalheaders?:Record<string,string>
Defined in: packages/observability/src/cost-guard-alert-sinks.ts:30
Optional bearer / signing header.
#url
url:
string
Defined in: packages/observability/src/cost-guard-alert-sinks.ts:26