On this page

Mesh status and debug view

GET/fleet/mesh

Operation getFleetMeshAuthBearer token

Query parameters

NameTypeDescription
debugstring

1 or true: include the debug info

sinceSeqinteger

Message-log cursor: only newer entries

Responses

StatusDescriptionBody
200OKFleetMeshStatus
runningboolean
agentsarray<object>
messageLogarray<object>
logSeqinteger
logIncrementalboolean
errorstring
Errors 400 · 401 · 403
400Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/fleet/mesh" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Fleet status rows

GET/fleet/status

Operation getFleetStatusAuthBearer token

Responses

StatusDescriptionBody
200OKFleetStatus
runningrequiredboolean
agentsrequiredarray<object>
Errors 401 · 403 · 500
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/fleet/status" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Token burn per agent and fleet

GET/fleet/burn

Operation getFleetBurnAuthBearer token

Responses

StatusDescriptionBody
200OKFleetBurn
perAgentrequiredmap<string, FleetBurnEntry>

Keyed by agent file path

4 fields of perAgent
tokensPerMinnumber
inPerMinnumber
outPerMinnumber
totalTokensnumber
fleetrequiredobject
4 fields of fleet · FleetBurnEntry
tokensPerMinnumber
inPerMinnumber
outPerMinnumber
totalTokensnumber
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/fleet/burn" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Restore lifetime burn totals

POST/fleet/burn/hydrate

Operation hydrateFleetBurnAuthBearer token

The client keeps the totals across restarts and hands them over once per session; rates start fresh.

Request bodyapplication/json · FleetBurnHydrateBody · required

FieldTypeDescription
burnTotalsrequiredmap<string, number>

File path → lifetime tokens (Studio client key fleetMapState.burnTotals)

Responses

StatusDescriptionBody
200OKSuccessResponse
successrequiredboolean
Errors 400 · 401 · 403
400Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/fleet/burn/hydrate" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"burnTotals":{}}'
Response 200
{
  "success": true
}

Mesh view poll in one call

GET/fleet/map

Operation getFleetMapAuthBearer token

Query parameters

NameTypeDescription
sinceSeqinteger

Message-log cursor for the debug slice

Responses

StatusDescriptionBody
200OKFleetMapPoll
debugrequiredFleetMeshStatus | null

running and agents (mesh-registered agents with live states). With debug: the mesh debug info (busRegistrations, backgroundAgents, foregroundAgents, messageLog), logSeq (newest log seq) and, with sinceSeq, logIncremental: true and only newer log entries; error when the debug read failed.

6 fields of debug
runningboolean
agentsarray<object>
messageLogarray<object>
logSeqinteger
logIncrementalboolean
errorstring
fleetrequiredobject

Mesh view rows (AgentVitalsService.getFleetStatus)

2 fields of fleet · FleetStatus
runningrequiredboolean
agentsrequiredarray<object>
burnrequiredFleetBurn | null
2 fields of burn
perAgentrequiredmap<string, FleetBurnEntry>

Keyed by agent file path

4 fields of perAgent
tokensPerMinnumber
inPerMinnumber
outPerMinnumber
totalTokensnumber
fleetrequiredobject
4 fields of fleet · FleetBurnEntry
tokensPerMinnumber
inPerMinnumber
outPerMinnumber
totalTokensnumber
adaptersrequiredobject
2 fields of adapters · AdapterStatusSummary
adaptersrequiredarray<AdapterState>

One per adapter type, healthiest instance

6 fields of adapters
typerequiredstring
statusrequiredstring

One of connected, connecting, disconnected, error

errorstring
connectedAtinteger
restartCountrequiredinteger
logsrequiredarray<object>
3 fields of logs
timestamprequiredinteger
levelrequiredstring

One of info, warn, error, system

messagerequiredstring
perAgentrequiredarray<object>
2 fields of perAgent
filePathrequiredstring
adaptersrequiredarray<object>
4 fields of adapters
typestring
statusstring
errorstring
connectedAtnumber
peersrequiredarray<object>
Errors 400 · 401 · 403
400Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/fleet/map" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Recent tool calls per agent

GET/fleet/recent-tools

Operation getFleetRecentToolsAuthBearer token

Mesh-registered agents, plus loaded agents the mesh does not track (read from their loops). Keyed by file path.

Responses

StatusDescriptionBody
200OKRecentMeshToolsResponse
toolsrequiredmap<string, array<object>>

By agent handle

4 fields of tools
namerequiredstring
argsstring
isErrorboolean
timestamprequiredinteger
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/fleet/recent-tools" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Owner message to agents

POST/fleet/message

Operation messageFleetAgentsAuthBearer token

A chat turn on each running agent. An agent that is not running is started (review gate on, the emergency-stop gate reopened); when the start is refused the message is written into its loop.

Request bodyapplication/json · FleetMessageBody · required

FieldTypeDescription
filePathsrequiredarray<string>
contentrequiredstring

Responses

StatusDescriptionBody
200OKFleetMessageResult
deliveredrequiredarray<string>
failedrequiredarray<object>
2 fields of failed
filePathrequiredstring
errorrequiredstring
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/fleet/message" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filePaths":[],"content":"string"}'

Adapter states across loaded agents

GET/fleet/adapters

Operation getFleetAdaptersAuthBearer token

Responses

StatusDescriptionBody
200OKAdapterStatusSummary

Fields as in AdapterStatusSummary above.

Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/fleet/adapters" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Restart one adapter of an agent

POST/fleet/adapters/restart

Operation restartFleetAdapterAuthBearer token

Request bodyapplication/json · AdapterRestartBody · required

FieldTypeDescription
typerequiredstring

Adapter type

filePathstring

The agent hosting the adapter

Responses

StatusDescriptionBody
200OKSuccessErrorResponse
successrequiredboolean
errorstring

Why it did not succeed

Errors 400 · 401 · 403
400Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/fleet/adapters/restart" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"string"}'
Response 200
{
  "success": false,
  "error": "This approval is no longer pending — it was already resolved, timed out, or its agent stopped."
}

Agent vitals by file path

GET/fleet/vitals

Operation getFleetAgentVitalsAuthBearer token

The overview card of any .adf file, addressed by path as Studio's AGENT_VITALS is: a loaded agent is read from its open workspace, any other file with a readonly open, whether or not it is in a tracked folder. Same body and cache rules as GET /agents/{id}/vitals; the fleet scan behind agentsSpawned is refreshed when older than 30 s.

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file.

forcestring

Skip the cache: 1 or true. 0 and false are accepted and change nothing.

One of 1, 0, true, false

Responses

StatusDescriptionBody
200VitalsAgentVitals
filePathrequiredstring
computedAtrequirednumber

When the stats and counts were computed (ms epoch)

liverequiredboolean

True when read from the workspace of a loaded agent

handlerequiredstring
namestring
didstring
agentIdstring
modelstring
createdAtstring

adf_created_at (ISO 8601)

ageDaysrequirednumber
statusstring

The agent's own status line (adf_meta status); absent when unset

descriptionstring

config.description, as on the ALF card; absent when blank

publicrequiredboolean

config.serving.public.enabled, the ALF card's public

ownerVerifiedrequiredboolean

An owner attestation about the current DID is stored, unexpired and its signature verifies (whether or not the card publishes it)

contextTokensinteger

Last API-reported context size (loaded agents only)

contextThresholdinteger

Compact threshold (present with contextTokens)

nextWakeAtnumber

Earliest next_wake_at among non-expired timers (ms epoch)

cost7dUsdnumber

USD over the last 7 local days, summed from the agent's priced adf_loop rows (the activity read's daily cost)

cost7dPartialboolean

True when some calls in the window had no recorded price or were compacted (cost7dUsd is a lower bound)

metricsrequiredarray<object>

adf_meta rows whose key starts with metric:, by key, at most 20. A value is a plain string, or a JSON object {"value": number|string, "label"?, "unit"?, "min"?, "max"?, "target"?}; parsed fields are returned beside raw. A value that is not such an object is returned as value = raw. Not part of any stat.

8 fields of metrics
namerequiredstring

Key without the metric: prefix

labelrequiredstring

The object's label when given, else name

valuerequirednumber | string

The object's value, or the raw string when the stored value is not a metric object

unitstring
minnumber

Bar start when max is set (default 0)

maxnumber
targetnumber
rawrequiredstring

The stored adf_meta value as is

statsrequiredobject
4 fields of stats
reachrequiredobject

Reach, Access or Autonomy: a capped level on a 1-20 scale. fill = clamp(points / max, 0, 1); level = 1 + round(19 * fill), so an empty config is Lv 1 and a maxed-out one Lv 20. max is the sum of every capped positive factor of the stat (counts such as MCP servers and chat adapters only count their heaviest few). Gated points count toward the level. points is open + gated.

9 fields of reach · AgentPowerStat
levelrequiredinteger

range: 1–20

pointsrequirednumber

Points behind the level, after mitigations

range: ≥ 0

maxrequirednumber

Points of a maxed-out config for this stat

> 0

fillrequirednumber

points / max, clamped: how much of the possible power the agent has

range: 0–1

openrequirednumber

Points whose capability runs without approval (mitigations come off these first)

gatedrequirednumber

Points whose capability needs approval

highrequiredboolean

True when open / max >= 0.6 (open level 12 or more): much of this runs without anyone asking

rawPointsrequirednumber

Sum of factor points, mitigations included

factorsrequiredarray<AgentStatFactor>
5 fields of factors
idrequiredstring

Stable id, e.g. tool:compute_exec, mcp:github, visibility

labelrequiredstring
pointsrequirednumber

Points this factor adds; negative for mitigations; 0 for an item past its kind's cap (7th MCP server, 4th chat adapter), listed but not counted

gatedrequiredboolean

True when the capability needs human approval

configPathrequiredstring

Config path (or table) that controls this factor

accessrequiredobject

Reach, Access or Autonomy: a capped level on a 1-20 scale. fill = clamp(points / max, 0, 1); level = 1 + round(19 * fill), so an empty config is Lv 1 and a maxed-out one Lv 20. max is the sum of every capped positive factor of the stat (counts such as MCP servers and chat adapters only count their heaviest few). Gated points count toward the level. points is open + gated.

Fields as in AgentPowerStat above.

autonomyrequiredobject

Reach, Access or Autonomy: a capped level on a 1-20 scale. fill = clamp(points / max, 0, 1); level = 1 + round(19 * fill), so an empty config is Lv 1 and a maxed-out one Lv 20. max is the sum of every capped positive factor of the stat (counts such as MCP servers and chat adapters only count their heaviest few). Gated points count toward the level. points is open + gated.

Fields as in AgentPowerStat above.

experiencerequiredobject

Experience. xpForLevel(L) = 5 * (L - 1)^2.25; level = largest L with xpForLevel(L) <= score.

7 fields of experience · AgentExperienceStat
levelrequiredinteger

range: ≥ 1

progressrequirednumber

Progress within the current level

range: 0–1

scorerequirednumber

Total XP (sum of signal XP)

levelStartrequirednumber

XP at which the current level starts

nextLevelAtrequirednumber

XP at which the next level starts

breakdownrequiredarray<object>
4 fields of breakdown
idrequiredstring

One of contextsWorked, memoryTokens, skills, localTables, localRows, filesWritten, agentsSpawned, messages, ageDays

labelrequiredstring
valuerequirednumber

Raw count

xprequirednumber

XP this signal adds

nextLevelrequiredobject

What one more level takes (xp = nextLevelAt - score), in units of the cheapest signals

5 fields of nextLevel
xprequirednumber
contextsrequiredinteger

Contexts of work worth the remaining XP

memoryTokensrequiredinteger

Memory tokens worth the remaining XP

skillsrequiredinteger

Skills worth the remaining XP

hintrequiredstring
maturityrequiredobject

Raw maturity counts read from the agent's file.

9 fields of maturity · AgentMaturity
contextsWorkedrequirednumber

Contexts of work over every loop (main, side, deleted): archived loop snapshots in adf_audit (one context at half the loop's compaction threshold or more, else its share) or live compaction summaries when loop audit is off, plus each live loop's current fill as a 0..1 share of its compaction threshold

range: ≥ 0

filesWrittenrequiredinteger

adf_files rows changed after the agent was created, mind/ excluded

memoryTokensrequiredinteger

Approximate tokens in mind/ files: total bytes, less the seeded mind/log.md header, / 4

localTablesrequiredinteger

local_* tables

localRowsrequiredinteger

Rows across local_* tables (the first 50 by name)

skillsrequiredinteger

Distinct skills the agent installed or changed

agentsSpawnedrequiredinteger | null

Tracked agents whose adf_parent_did names this agent; null when no fleet scan has run

messagesrequiredinteger

Loop messages ever written, every loop current and past (adf_loop's shared AUTOINCREMENT high-water mark; compaction, clears and loop deletion do not lower it)

ageDaysrequirednumber

Days since adf_created_at

Errors 400 · 401 · 403 · 500
400Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/fleet/vitals?path=PATH" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Agent activity by file path

GET/fleet/activity

Operation getFleetAgentActivityAuthBearer token

The overview's lower sections for any .adf file, addressed by path as Studio's AGENT_ACTIVITY is. Same body and cache rules as GET /agents/{id}/activity.

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file.

forcestring

Skip the cache: 1 or true. 0 and false are accepted and change nothing.

One of 1, 0, true, false

Responses

StatusDescriptionBody
200ActivityAgentActivity
filePathrequiredstring
computedAtrequirednumber

When this read was computed (ms epoch)

liverequiredboolean

True when read from the workspace of a loaded agent

upcomingrequiredarray<AgentUpcomingWake>

Next non-expired timers, soonest first

items: ≤ 3

7 fields of upcoming
idrequiredinteger
atrequirednumber

next_wake_at (ms epoch)

scoperequiredstring

system runs a lambda; agent wakes a loop

One of system, agent

lambdastring

system: lambda reference, e.g. lib/sync.ts:run

inputstring

system: payload passed to the lambda

length: ≤ 1000

loopstring

agent: loop the wake dispatches to (main when the timer names none)

promptstring

agent: payload the loop wakes with

length: ≤ 1000

dailyrequiredarray<AgentActivityDay>

14 local days, oldest first; the last is today

items: 14–14

5 fields of daily
daterequiredstring

Local YYYY-MM-DD

messagesrequiredinteger

adf_loop rows of every role created that day, plus the day's estimated share of compacted rows archived in adf_audit

estimatedboolean

Some of the day's messages are compacted history whose timing is estimated (spread evenly over a span ending at the archive's creation)

costUsdnumber

USD of the day's priced adf_loop rows (cost_usd in the row's usage record); absent when none had a price

costPartialboolean

Some calls that day had no recorded price, or were compacted (their cost is not recorded); costUsd is a lower bound

contentsrequiredobject

What the file holds, in three groups. Tokens are approximate (bytes / 4, rounded) and given for mind and skills only: table data is rarely read into context.

3 fields of contents
mindrequiredobject

Files under mind/

4 fields of mind
filesrequiredinteger
tokensrequiredinteger

SUM(size) / 4, rounded, the seeded mind/log.md header taken off that file

updatedThisWeekrequiredinteger

mind/ files whose updated_at is within the last 7 days

stratarequiredobject

Current mind/ tokens (size / 4, rounded, the seeded mind/log.md header taken off that file) split by each file's updated_at. A boundary belongs to the younger band.

4 fields of strata
olderrequiredinteger

Last updated more than 90 days ago

quarterrequiredinteger

Last updated more than 30 and at most 90 days ago

monthrequiredinteger

Last updated more than 7 and at most 30 days ago

weekrequiredinteger

Last updated at most 7 days ago

skillsrequiredobject

Skills the agent installed or changed (the Experience stat rule)

2 fields of skills
countrequiredinteger
tokensrequiredinteger

Size of every file under those skills' directories / 4; registry entries without files add 0

tablesrequiredobject

local_* tables (at most 50 read)

2 fields of tables
countrequiredinteger

range: ≤ 50

rowsrequiredinteger

Total rows

Errors 400 · 401 · 403 · 500
400Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/fleet/activity?path=PATH" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Set the state of running agents

POST/fleet/state

Operation setFleetAgentStateAuthBearer token

Studio's MESH_SET_AGENT_STATE: for each file, end any active turn and enter idle or hibernate. A file with no loaded agent fails with agent offline; a stopped or errored executor with agent stopped / agent error. Any other state fails every file with invalid state.

Request bodyapplication/json · FleetStateBody · required

FieldTypeDescription
filePathsrequiredarray<string>
staterequiredstring

One of idle, hibernate

Responses

StatusDescriptionBody
200OKFleetStateResult
updatedrequiredarray<string>
failedrequiredarray<object>
2 fields of failed
filePathrequiredstring
errorrequiredstring
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/fleet/state" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filePaths":[],"state":"idle"}'

Found an agent from the Mesh view

POST/fleet/found

Operation foundFleetAgentAuthBearer token

Studio's MESH_FOUND_AGENT: dir must be inside a tracked folder, or with newRoot: true a sibling of a tracked root. The folder is created when missing, the file is <slug of name>.adf, made from the default template with its identity, marked reviewed, left closed, and its folder tracked. Failures answer 200 with success: false and error.

Request bodyapplication/json · FleetFoundBody · required

FieldTypeDescription
dirrequiredstring

Absolute folder for the new agent.

namerequiredstring
newRootboolean

Responses

StatusDescriptionBody
200OKFleetFoundResult
successrequiredboolean
filePathstring
errorstring
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/fleet/found" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dir":"string","name":"string"}'