Agent API by domain

The Agent exposes one current Candid service. Download the annotated interface or generated TypeScript declarations for complete arguments, results, and variants.

The tables below are an index into that contract. They do not replace method authorization or imply that every installed Agent supports the current methods.

Discovery and compatibility

Method	Purpose
handshake	Resolve caller connection, effective role, and access origin
getCompatibility	Read the protocol/schema compatibility envelope
getManifest	Read Agent identity and the fields this caller may see; capabilities require Admin
getViewerAccessPolicy	Discover the authenticated viewer publication policy
attestUpgradeState	Check the installed Agent’s post-upgrade state under lifecycle authority

For example, these are query methods with no input arguments:

handshake: () -> (AgentCanisterConnection) query;
getCompatibility: () -> (AgentCanisterCompatibility) query;
getManifest: () -> (AgentManifest) query;

Connection, wire compatibility, feature capability, and target control are separate checks. Upgrade discovery must remain possible even when an older Agent lacks newer feature methods. Use the upgrade guide for that lifecycle.

Registry, People, and shared documents

Domain	Representative methods	Access and concurrency
Registry	listRegistryCanisters, getRegistryCanister, upsertRegistryCanister, archiveRegistryCanister	Permitted retained reads; content writes require Read-write or Admin and current revision checks
Saved views	listSavedViews, putSavedView, deleteSavedView	Anyone who may read the Registry sees every view; writes require Read-write or Admin and current revision checks
Availability checks	listAvailabilityChecks, estimateAvailabilityCheck, putAvailabilityCheck, deleteAvailabilityCheck	Anyone who may read the Registry lists and prices checks; writes require Read-write or Admin, the current Registry revision and current check revision
Log collection	getLogCollection, listCanisterLogs, setLogCollectionPolicy	Anyone who may read the Registry sees the policy and coverage; only active members read collected lines; only an active Admin saves the policy, at the current revision
People	listAgentMembers, upsertAgentMember, setAgentMemberStatus, removeAgentMember	Admin
Dashboards	listDashboards, getDashboard, createDashboard, updateDashboard, restoreDashboardVersion	Permitted retained reads; role-gated, versioned content writes
Reports	listReportDefinitions, generateReport, listReportRuns, getReportRun	Retained reads and separately authorized generation/definition changes
Operational summaries	getSourceSummary, getOperationalFleetSummary, listOperationalCanisters	Bounded retained views; fleet pagination binds the expected Agent revision
Timeline	listCanisterTimeline, listFleetTimeline, refreshCanisterTimeline	Retained reads are distinct from refreshing external evidence

Use the returned cursor for the next page. A numeric cursor is opaque navigation state, not a record count. Where a method takes expectedRevision or expectedAgentRevision, a mismatch means reload current data before proposing a new write or continuing a consistent view.

One Agent supports at most 200 members and 250 Registry canisters, including active and archived Registry entries.

The Registry edit UI accepts names up to 120 UTF-8 bytes, at most 50 unique tags of 80 bytes each, and notes up to 500 characters within 2,000 bytes. These are distinct from the browser backup schema bounds.

A saved view is a named filter and sort set that everyone who can read the Agent’s Registry sees. One Agent keeps at most 50 saved views. A name is 1 to 64 characters and unique within the Agent, ignoring case; a tag filter is at most 80 bytes. Omit the view id to have the Agent allocate the next view-<n> id; deleted ids are not reused. Saved-view writes are audited and do not change the Agent revision, so they never interrupt fleet paging.

An availability check is an opt-in, Agent-paid call to one Registry canister on a whole-minute cadence from 1 minute to 24 hours. One Agent keeps at most 25 checks, one per canister. Each attempt is a replicated HTTPS outcall that posts an anonymous query envelope to the IC’s public /api/v3/canister/<id>/query endpoint, either a no-argument Candid query method or the public http_request query with a GET of one path. A check never sends an update call. Only the management canister may call the transformAvailabilityCheck consensus transform, which keeps only the outcome: replied, rejected with the IC reject code, protocol_error for a malformed, oversized (over 8 KiB) or non-200 response, or transport_error when the outcall fails or times out. Only replies and rejects say anything about the target. The round trip runs from issuing the outcall to its consensus-delivered response, so it includes subnet consensus and is not query latency.

Saving binds the check to the exact Registry record and revision the caller reviewed. The saving member becomes the configuring member, whose Read-write or Admin authority the Agent renews before every attempt; losing it, or archiving or re-pointing the Registry record, suspends the check and discards any response still in flight. daily_cycle_limit is the most the check may attach to outcalls in one UTC day, at least one attempt’s fee and at most 1 TC. The Agent charges each attempt to the day before the outcall is sent; an attempt that would exceed the limit, or that the Agent’s operating reserve refuses, is skipped and never replayed, and saving again never resets the day’s spend. Checks run only on an Agent installed with the production environment marker; other Agents may save them paused. estimateAvailabilityCheck prices a probe with the live outcall fee: on a 13-node subnet one health query costs 135,584,800 cycles, about 0.195 TC a day at one check a minute. The Agent’s own execution of each attempt adds about 82 million cycles (about 0.31 TC a day in all at one check a minute, 0.063 TC at five minutes), and each attempt in flight temporarily holds about 0.25 TC of the Agent’s balance as the IC’s refundable callback prepayment. Attempt history is the iclens.canister.availability.* telemetry described in the signals catalog.

Log collection has one Agent-wide policy and one collection per Registry canister. An active Admin saves whole-minute intervals from 60 to 3,600 seconds, a daily sampling allowance of 64 KiB–2 MiB per canister with the current policy revision. Logs retention is read-only in this policy and is managed through configureEngines. Retention applies to new blocks in every Logs namespace; existing blocks keep their original trusted-arrival expiry. New namespaces inherit the setting. The saving Admin remains the policy author; losing Admin suspends collection. The Monitor switch gates collection.

The current maximum is the greatest whole-day duration whose expiry fits Nat64 at trusted time. Namespace changes preflight first, then use fresh native plans and commits in one synchronous transaction. Engine-management validation reports native class-pressure or invalid durations before mutation. At most six distinct configured and eight configured-plus-draining classes can exist. Expiry eligibility is not a guaranteed release time: maintenance and blockers must also permit retirement. No automatic retry bypasses these limits. Fresh append also checks expiry overflow. A duration close to the timestamp maximum can stop being admissible as trusted time advances; lower the setting before that boundary rather than assuming configuration reserves future intake.

The collector reads at most 500 records and selects at most 256 KiB of logical line bytes per reply, with at most 25 reads per wake. It preserves up to 1,024 content bytes per line and the original size. Above the sampling allowance, info/debug lines are selected one in ten by IC index; warnings/errors/traps are not sampled. Embedded Lumera is the sole payload store. Its shared ceiling and native admission refusals bound storage; no per-collection row cap or severity eviction remains. Refused storage is reported as a coverage gap and zero stored lines. Processed source indices and minute metrics advance once.

listCanisterLogs returns one bounded contribution, an authenticated continuation and complete. Only a completed chain establishes exact range/matched totals and final IC-index order. The client keeps at most 201 rows to assemble a page of at most 200. Times remain half-open; text is a UTF-8 message substring (1–64 bytes). The app defaults case_insensitive to true, folding ASCII A–Z only; Match case sends false. Non-ASCII bytes compare exactly. before_idx selects older indices. Progress is provisional and may be stopped. Retirement, changed configuration or hidden collection generations invalidate continuation; callers restart rather than label an invalidated result complete. Later appends do not join the snapshot.

Active members alone read collected payloads. Generic Lumera methods exclude the reserved namespace. Removal/re-pointing hides old generations immediately; their bytes expire normally. Manual erasure is unavailable. These payloads are accounted within lumera_engine, never a second canister_logs store. Bounded overview occupancy that has not been measured is optional, not zero.

Operational canister rows also carry the latest observed memory_allocation, wasm_memory_limit, and wasm_memory_size. The memory_high attention reason means memory use is at or above 85 percent of a nonzero memory allocation or Wasm memory limit.

Metra

Work	Methods
Status and supported query limits	metraStatus
Arena ceiling configuration	configureEngines (active Admin, exact global Agent revision and operation identity)
Descriptor and series discovery	metraMetadata, metraLabelNames, metraLabelValues, metraSeries
Chart configuration	telemetryReadContext
Native and PromQL queries	telemetryReadBatch
Protocol V3 producer	open_producer_stream, register_descriptors, register_group, extend_group, append_strips, reconcile_producer_cursor, close_producer_stream
Prometheus HTTP reader	metraConfigureHttpReader, metraHttpReaderStatus
Scoped producer lanes	observabilityListProducerLanes, observabilitySetProducerLane

Read authority, accepted producer scope, and Admin configuration are separate. Query the accepted capability revision and enforced bounds rather than copying engine defaults. SDK transports use the same V3 producer contract; the Agent adds Registry or forwarder grant authorization before decoding.

Producer lanes are bounded to 32 exact principal/signal/scope grants. Changes compare the complete prior grant and current revision, audit the outcome and preserve unrelated lanes. Revocation immediately removes intake authority. Per-lane request, calls-per-minute and bytes-per-minute limits precede native decoding. Owner/member principals cannot become dedicated lane producers.

Headless native observability

These headless APIs expose backend capabilities without adding product journeys or changing existing dashboards. Inclusion is not release qualification. observabilityComponentInfo reports the four exact embedded source commits; network/root trust always comes from the client configuration.

Boundary	Methods
Native configuration/accounting	observabilityBootstrap, observabilityConfigureMaintenance, observabilityStorage, observabilityScopes, lumeraConfigureNamespace, veyraConfigureScope
Lumera producer SDK	registerRecipe, appendNative
Lumera ordinary queries	lumeraRead, lumeraReadText, lumeraPoll, lumeraFields, lumeraVolume, lumeraTopValues, lumeraPatterns, lumeraSurrounding
Veyra producer SDK	register_producer_in, ingest_packet_in, get_receipt_in
Veyra ordinary queries	veyraSearch, veyraLookup, veyraReceivedSpanSummaries, veyraResolvedGraph
Metra exemplar primitives	append_strips_exemplars, metraExemplars
Technical definitions	observabilityConnections, observabilityPutConnection
Independently callable provisioning	observabilityCreateStore, observabilityAdoptStore (a RUM collector you run: management readback proves the Agent and you control the exact certified release; nothing is created, installed or funded), observabilityStageStoreChunk, observabilityInstallStore, observabilityInstallChunkedStore, observabilityUpgradeStore (same product, memory kept, hash readback), observabilityConfigureStore (including RUM rum_collector_settings and rum_apply_configuration)
Traces lifecycle	observabilityDeleteTraces (Admin; one scope’s data, all or an arrival range, or with no scope a whole reset, at the last operation ID read from observabilityStorage’s traces_lifecycle); capacity grows through configureEngines
Logs lifecycle	observabilityResetLogs (Admin, whole store, at the incarnation read from observabilityStorage’s logs_reset)
Reconciliation queries	observabilityProvisionOperation, observabilityProvisionOperations (the whole journal, for setups in progress), observabilityManagedReaders
Collector administration	observabilityCollectorStatus (active Admin; exact managed creation/adoption and optional app; fixed native configuration, diagnostic switches and their independent revisions)

The ordinary Lumera reads (lumeraRead, lumeraReadText, lumeraPatterns, lumeraFields, lumeraTopValues, lumeraVolume, lumeraSurrounding) also accept the collected canister-logs namespace for active members only, the same gate as listCanisterLogs. Results contain and count only the canisters listCanisterLogs would read; not_searched lists any canister whose records were withheld or that the request named without access, so the result is partial for it. Every other namespace returns an empty not_searched.

veyraResolvedGraph returns the native graph plus senders: for each declared service and version on its edges or recorded in the scope (a service that calls nothing in the window included), the trace sender recorded at authenticated ingest. It names a canister only when that canister delivered the spans over its own lane and declares a single service name; a forwarder or multi-service lane is forwarded, two canisters sharing a declaration are multiple, and no record is unknown, each with the last delivery time. The table holds no span payload or attributes and is bounded per scope and in total.

observabilityStorage exposes the agent-memory-budget-v2 defaults and host limits alongside current usage: Metra 4 GiB arena, Lumera 4 GiB ceiling (Admin-adjustable in 64 MiB steps through 16 GiB), Veyra 64 GiB worst-case live blocks (Admin first-enable 2 MiB steps through 64 GiB), 64 scopes, eight log namespaces and 32 shared producer lanes. Block/receipt/scope and namespace/lane used counts remain separate from byte accounting. Veyra capacity is immutable in the pinned package. Retention maintenance defaults on; Admin pause, quiesce and the cycles floor remain effective. The shared compiled Region ceiling is 100 GiB. Unknown measurements remain optional. See the combined memory plan for estimates, headroom and the limits of these ceilings.

getEngineStatus reads each optional engine’s lifecycle, retained allocation, configuration and known dependencies. configureEngines manages them under active Admin authority, a global expected revision and an exact operation identity. Fresh installs initialize none; enable creates native state once, retire stops intake, and re-enable retains that state. Metrics, Logs and Traces may be selected independently, subject to producer/Monitor dependencies and the 84 GiB bulk planning limit. Veyra capacity is immutable after first enable. No purge/reset exists.

Configuration requires active Admin and exact revision. Native reads require current read access, make no external calls, run no maintenance and have no paid fallback. Missing or forbidden namespaces return the same denial. Lumera analytics require complete populations of at most 64 matches; signed read and poll cursors bind caller, scope, full request, revision and expiry. Veyra graph results are bounded query-time views. Identity misses do not establish expiry, redaction or sampling. Frontend investigations read the collector’s retained metrics, errors, events, timelines, issue-impact and release reports directly under each member’s own identity. Original source additionally requires its verified protected-host release binding.

Provisioning requires an operational Agent and a pinned artifact identity. A durable operation ID precedes create/fund/install/configuration effects. Creation attaches explicitly supplied cycles and retains both Agent and initiating human as controllers. Uncertain results require retained-ID reconciliation; there is no automatic re-creation, reinstall, orphan deletion or direct-execution fallback. Raw installed Wasm hashes, rather than reported versions, settle installation. Configuration accepts a closed native command union only for managed stores. Collector commands include application configuration, embedded storage, event and timeline policies, and diagnostic switches. Each review retains the exact native CAS revision for that operation; the diagnostic revision is independent of storage and reader revisions. Private arguments, keys and response bytes are not retained in journals.

Collector access follows active Agent membership automatically, up to 32 people per collector. The managed access journal retains acknowledgements and uncertain outcomes, reconciles against native readback, and drains remaining work through the Agent’s existing timer. Member deactivation and removal revoke managed access; independent canister-controller authority remains separate. Excess membership is reported explicitly rather than treated as provisioned. Other standalone stores retain their explicit managed access intents.

Collectors keep their embedded engines locally; no destination producer or external store is configured. Setup applies the reviewed configuration with collection off, then enables it explicitly. Frontend Monitor rules use the existing Custra remote-source path. Metric rules evaluate bounded five-minute rates or populations. The closed rum:new-issues-in-latest-release:<app> query returns a Boolean only after sufficient accepted catalogue history; incomplete evidence never becomes a healthy false result. App identifiers are canonical nonzero Nat32 values, and the provider authorizes its controlling Agent.

The new-issue watch uses the preceding five minutes of collector acceptance time. A new issue is an application’s first accepted diagnostic fingerprint, first accepted in the uniquely latest observed approved release. Configuring a build alone does not make it latest, and a new build alone does not make an unchanged fingerprint new. Consent and sampling limit which errors reach the collector; tied or incomplete release history remains unavailable.

The public TypeScript boundary is src/services/ic/observability/index.ts. Its native results retain exact integer, integrity, population, work and limit metadata. Query transport uses the existing read scheduler and Source/caller/ network/root guards. Server capability facts remain unknown until observed; compiled, qualified, enabled, available and permitted are separate claims.

telemetryReadContext returns collection cadence, retention, query limits, capability revision and batch limits without scanning retained metrics. telemetryReadBatch accepts typed native_instant, native_range, promql_instant or promql_range requests with unique numeric IDs. Both are ordinary query calls from the browser to the selected Agent. The Agent reads its embedded engine synchronously; these methods make no intercanister calls. Results retain the engine’s rawUncertified query trust.

A message accepts one to eight native reads, or one PromQL read, with a maximum encoded request of 64 KiB and response budget of 1 MiB. Native items share one work reservation and retained index. Each item keeps its exact selector and independent engine evaluation; the Agent does not broaden a selection to scan unrelated platform metrics. Returned counts and work statistics describe each item. An incomplete result never becomes a complete empty answer. Authorization requires current passive-read access and the Agent constructs the protected origin context itself.

Each returned ID has a typed success, error, or retry_separately outcome. Retry only deferred items as singleton requests. Do not replay successful siblings. A trap rejects the entire message; the frontend regroups a multi-item message once only for an explicit replica instruction-limit rejection. Network, authority and deterministic input errors do not trigger regrouping. Older numerical method names are removed from the current Candid contract; upgrade discovery remains available independently of this feature.

Engine initialization and capacity

A fresh Agent obtains 32 random bytes from the management canister on its first timer wake and keys Metra’s indexes once. Until that succeeds, producer updates return notReady without publishing data. Failed entropy retrieval retains a recovery wake. Index keys and seed bytes never appear in status or audit.

The capacity report includes the optional host ceiling, platform growth refusals, reusable space, index split debt, active series, closed groups, and quarantine count. Each write plan admits independently and reserves physical growth using measured instruction headroom. icLens applies per-producer quotas without a global series ceiling or active-series budget.

Refusal	Meaning
activeSeriesBudget	An embedding host’s optional active-series budget is exhausted; icLens does not configure this budget
storageExhausted	The host ceiling or platform prevents allocation
maintenanceDue	Bounded index splits must progress before another admission attempt
group(unknownGroup)	The group is closed or unknown; register it again before writing

Refusals never authorize silently dropping observations. Closing a group does not delete its retained observations. Logical retention can hide observations before extents are reclaimed; the engine deadline controls further physical work. See the storage lifecycle.

Custra and Monitor

Work	Representative methods
Configuration and health	custraStatus, custraConfigurationPage, custraReplaceConfiguration
Scheduling and the Monitor switch	getMonitorScheduleStatus, setMonitorScheduleConfig, runMonitorSchedulerNow
Alert instances and evidence	custraInstances, custraInstance, custraAlertHead, custraHistory, custraDeliveries
Receiver credentials and HTTPS budget	custraPutSecret, custraDeleteSecret, custraSetHttpBudget
Finite top-up authority	custraFundingAuthorizations, custraAuthorizeFunding, custraRevokeFunding
Transfers and recovery	custraTransfers, custraAssessFunding
Manual wake	custraRunNow

Active members can read status, instances, deliveries, and bounded history. Rules and sources use eight-item configuration pages pinned to configuration revision. Receiver configuration, credentials, grants, and transfer evidence require Admin because receiver URLs and funding details can be sensitive. A grant is finite and bound to the current receiver, rule, source, Agent, reserve, fee ceiling, and expiry. Only the immutable Agent owner can close an uncertain transfer as spent after authoritative review. External-owner funding accounts are not in the first icLens interface.

Instances use per-rule subject cursors pinned to evaluation, with at most 256 returned items and a bounded filtered scan. A short filtered page may still have a continuation. Exact rule/subject lookup avoids scanning; the active preview returns at most 32 instances with an exact total. Delivery and funding-authorization pages use stable ID cursors with at most 32 items. Transfer pages read newest first, at most 32 receipts, for one canister when a target is given, and continue before the last receipt read; a page has a continuation only while an older match remains, and a target scan visits at most the retained receipts. Funding grant pages carry a mutation revision. History uses a bounded sequence cursor (64 events) and reports a pruning gap. Restart instance/configuration collections after a revision conflict.

Monitor scheduling diagnostics

getMonitorScheduleStatus exposes last_full_sweep, last_round_cycles and current_sweep. A round ends after all scoped canisters have been attempted, including denied reads; its duration spans the first pass start to the last pass end. Only Monitor-on passes count as rounds. Paused one-shot access checks do not.

last_round_cycles is what the last full round’s reads cost. The Agent prices each pass at its own subnet’s fees: the workers’ measured call-context instructions, plus a counted message, call fee and Candid bytes for every management read and worker start. The IC fee schedule is published for a 13-node subnet; the Agent scales it by its live canister-creation cost. Change-history reads count as instructions, not calls.

host_scheduler reports the actor-lifetime epoch and a bounded count of committed host-timer entries across Agent duties, not successful collections. Compare differences only within the same epoch while saturated is false. Upgrade starts a new epoch; traps before the timer’s first commit are not counted. Simulated runtimes can omit this diagnostic.

Its eight duty_dispatches entries count admitted domain leases. Several domains can share one host-timer entry; a dispatch is not a successful read. synchronous_samples and optional synchronous_instructions cover the measured maintenance, Lumera, Veyra and log-reply segments only. Log callbacks can produce several samples per dispatch. Missing measurements remain unknown. These instruction counts exclude scheduler preparation, transport, other asynchronous work, reply encoding and collection after the segment; they are neither cycle charges nor total execution cost. Compare only equal, nonsaturated epochs.

runMonitorSchedulerNow forces at most 25 targets, including while Monitor is off. Ordering is never-successfully-read targets, then oldest successful read, then oldest attempt. Repeated passes advance through scope without changing the cadence of not-yet-due work.

Each pass has at most four concurrent workers. Each worker handles status, optional consumption, and due protocol history before its next target. Observations become available as they commit; the final summary waits for history reads. Every outstanding read has a recovery deadline. A lost read revokes the pass and discards late callbacks, without removing already committed observations. Undispatched targets retain due slots; consumed slots are not replayed.

Settled Agent cycles

getAgentCyclesBalance is available to active Read-write and Admin members. It returns balance and IC timestamp only when the Motoko runtime has no outstanding callbacks. Otherwise the UI retains its last settled query with the original timestamp, or waits if none exists. This query creates no history.

Self-monitor status history includes temporary collection-call reservations. Even an update’s pre-call Cycles.balance() can be low because the executing message has its own reservation; moving the read cannot remove this effect. Other targets’ figures and the nine cumulative consumption counters are unchanged. Reconcile current cycles with a settled query or controller status, allowing for spending between timestamps. See the IC cycle accounting contract.

Subnet collection

Work	Bound or cadence
Resolve hosting subnet	NNS get_subnet_for_canister; at most 10 canisters per wake
Cache placement / retry lookup	One day / one hour
Read subnet metadata and node history	One subnet per wake, hourly
Node history	Experimental daily sparse cumulative counters; at most 60 samples

Placement never comes from the browser. Without an NNS on a local network, lookup fails and no subnet is read. History starts with the last day and advances an original-time cursor in bounded chunks. Missing nodes, reappearances, and membership gaps do not prove zero work, outage, or continuous counter differences. Evidence age must accommodate daily data. Replica version is inventory metadata, not an unbounded metric label.

Subjects are subnet:<principal> and node:<compact-subnet-principal>:<compact-node-principal> in the selected Agent. Compact text removes canonical base32 grouping hyphens only; neither principal is truncated. The longest pair is 112 bytes, under the 128-byte bound. Public subnet-wide certified aggregate metrics and verified billing policy are separate coverage; this collector does not scrape external /metrics endpoints.

Log collection timing and measured cost

Reads share a grid 35 seconds past each interval boundary, at most 25 targets per wake. Archiving stops collection and discards in-flight reads; re-pointing a Registry record starts a new collection for the new canister.

The historical cost model is about 80 million cycles per scheduled wake, 6.4 million per admitted target, and 0.12 million per processed line, paid by Agent execution cycles, not Reserve. These are measured baseline coefficients with marginal-target extrapolation, not a new SDK or 96-target benchmark. Overview shows last_round_cycles and a day of rounds at the configured pace; it does not synthesize a cost from these coefficients. Larger populations need multiple wakes. Coverage records and stored bytes cannot certify the complete current viewer population. See collection configuration.

Management, funding, and operational evidence

Live management methods such as canisterStatus, canisterInfo, and listSnapshots are update calls because the Agent performs external work. They require the management role and target checks even when the operator’s goal is inspection.

Mutating methods such as startCanister, installCode, and takeSnapshot carry an operation identifier. Snapshot capture, restore, and deletion return an AgentCanisterJobResult; inspect the returned job and live target state to establish completion. See the operation matrix.

Funding uses prepareAutomationReserveFunding, confirmAutomationReserveFunding, refreshAutomationReserve, funding-policy methods, and retained funding/top-up receipts. These methods do not form a generic wallet API. Use the funding guide for the exact asset path and recovery sequence.

Admin operational evidence includes listAuditLogPage, exportAuditLog, listOperationRecords, and reconcileOperation. Job methods apply ownership filtering for non-Admin active members.

Reserve accounting and reconciliation

The host journal reserves principal plus the admitted fee before withdrawal. Success uses the fee proved by the returned Cycles Ledger block; missing fee proof remains uncertain. Rolling debit uses conservative hourly buckets and can retain one extra boundary hour. Pruning history cannot reduce spend or cumulative totals. Closing an uncertain transfer without fee proof holds automatic funding for 25 hours while the owner reconciles the Reserve.

Refresh cannot overwrite the explained balance while withdrawals are pending. A higher raw balance needs confirmation through its retained deposit instruction or explicit Admin reconciliation after incomplete instructions are resolved. Known credits and settled debits update the explained checkpoint atomically, preventing a later deposit proof from counting the same credit twice.

Local funding rules require a simple host-owned platform selector. Native reads retain exact integers and original observation timestamps, including integers beyond JavaScript’s safe range. Formula rules may notify but cannot authorize local funding without equivalent provenance. Historical offset/@ expressions and subqueries are rejected; range windows must fit maximum evidence age. Complete-result limits follow the current Custra profile.

Protected iclens.reserve.* metrics expose explained balance, reserved and available cycles, incident state, evidence age, delivered cycles, and network fees. Their canister_id is the Agent principal. Private payer accounts and payment arguments are excluded.

Manual withdrawals reserve each target’s principal and admitted fee. Each dispatch rechecks authority, context, fee, expiry, and shared limits, including after live reads. Delivery needs both the ledger acknowledgement and matching fee proof; a burn transaction alone is insufficient. An exact refund charges only the proved net debit. Unknown or unproved outcomes retain reservations and block further funding. Review expiry leaves completed targets intact and fails undispatched targets without a fee.

The same exact operation ID returns retained receipts; changed inputs under that ID are rejected. Reconciliation reads acknowledgements and bounded ledger evidence without withdrawing again. Capacity is 10,000 protected target receipts; exhaustion blocks new manual funding without deleting recovery evidence. Follow the Reserve recovery guide.

AI and storage

AI APIs cover policy, context preview, questions, threads, turns, jobs, digests, and bounded OQL investigation. Interactive calls require active Read-write or Admin and current policy; retained conversation visibility has its own checks. See icLens AI before choosing or sharing context.

Storage APIs expose summaries, history, policy, cleanup previews, and cleanup runs. A preview is a read; execution is an Admin mutation that must preserve unresolved financial and external-effect evidence. See storage maintenance.

AI admission and digests

Inference checks live Agent cycles before quota acceptance and again immediately before the provider call. Balance must cover pending external attachments plus the strongest configured or active operating reserve, including the global one-trillion-cycle floor. Inconsistent attachment accounting fails closed. Inference attaches zero cycles; quotas and feature checks still apply. Custra HTTPS delivery has a separate admission boundary.

AI policy updates review the whole native record. The UI rereads its original update timestamp before dispatch; that read and update are not an atomic compare-and-swap. The Agent independently checks Admin authority and limits. Per-member daily limits are 1–1000, with an Agent-wide ceiling at least as large.

Digest settings validate bounded Source scope, UTC minute, enabled digest policy, and decimal IDs of enabled Custra delivery receivers. Top-up receivers cannot be destinations. Jobs are caller-owned even for Admins; digest artifacts are Agent-wide for active Read-write and Admin operators. The canonical read follows the current job cursor to its terminal page, up to 200 retained jobs, and reads at most 30 digest artifacts. Read-only members and published viewers do not inherit these populations.

A manual digest review binds its replay key, whole policy, schedule, destinations, and Agent revision. Confirmation renews original seat, method admission, and native records; this is a sequence of reads and an update, not a lock. Policy, settings, or Source drift requires a fresh review while keeping the original key. An expired key is rejected at its expiry boundary. A fresh key is new inference and quota work. Delivery retries require retained proof for the exact attempt.

Demo uses the same screens and guards with per-Agent memory-only records and authored evidence. It checks simulated own-canister balance against configured and global floors, with no pending external attachments in the current simulation. It contacts neither model nor receiver; simulated failed delivery is no proof of an external send. Validation, quotas, expiry, and retained retry admission remain the represented contracts. Follow the AI administration guide.