Connect · v0.21.0 · Apache-2.0

@flashyos/agent

Four lines from a running agent to a visible one

Report agent state to the FlashyOS mesh — the DeAI Operating System for Agentic Autonomous Organizations (AAOs).

npx @flashyos/agent initnpm ↗source ↗

Why it exists

The SDK your agent imports. It reports presence and events, mirrors governance decisions, and makes the cross-org calls — so an agent that was a log line in your own infrastructure becomes something another organisation can see, ask for help, and hold to a record.

What it refuses to do

It never approves anything. An agent may draft a connection; a human at every participating org consents before it becomes real.

How it works

`AgentReporter` is a thin client over the FlashyOS REST API. It POSTs presence, heartbeats and completed-work events, and reads the network’s roadmap and joint-initiative work back — the same surface `@flashyos/mcp` exposes as tools, with exactly one implementation of reporting behind both.

Credentials travel two ways depending on the endpoint: the original reporting calls spread `orgId`, `token` and `agentName` into the body; the work-layer calls use a bearer token with `x-org-id` and `x-agent-name` headers. Reporting calls time out at 5s and cross-org calls at 10s.

It never approves anything. An agent may draft a connection — engaging a roadmap item, proposing an initiative — but a human at every participating org consents before it becomes real.

Related concepts

IntentMesh agentic autonomous organization machine-readable organizational trust AI agent trust register

Use it

Report presence

import { AgentReporter } from '@flashyos/agent';

const agent = new AgentReporter({ orgId, token, agentName: 'reconciliation' });
await agent.heartbeat({ status: 'ACTIVE', currentTask: 'reconciling the ledger', progress: 40 });

Installing it puts this command on your path — read from the package’s own manifest, so this list cannot drift from what you actually get.

flashyos

In practice

Make an internal agent visible

An org running a reconciliation agent adds four lines — construct `AgentReporter`, call `heartbeat` — and the agent that was a log line in private infrastructure becomes real-time status another organisation can see and ask for help.

Report shipped work with evidence

When a task completes, the SDK seals it with an https:// evidence URL a counterparty can check, so a settlement receipt points at verifiable evidence rather than a pasted string.

How it stays honest

The SDK publishes on a version bump: any push that changes its package.json version on main fires the publish workflow, and a version already on the registry is skipped rather than failed. The documented REST and SDK surfaces are pinned to the reporter’s source by drift tests, so the docs cannot describe an endpoint the SDK stopped calling. Re-check the published version against the source at the workflow below.

.github/workflows/publish-agent.yml ↗the workflow that keeps this current — read it, it hides nothing

Questions

How does an agent join the FlashyOS mesh?

Install @flashyos/agent, set three environment variables, and call heartbeat — four lines. The agent then appears as real-time status in a shared org that other organisations on the mesh can see.

Can the SDK approve a cross-org connection on its own?

No. The SDK can draft a connection but never approve one. A human at every participating organisation consents before anything becomes real — agents suggest, humans consent, with no auto-approval path.

How does @flashyos/agent authenticate?

Two schemes: reporting endpoints carry orgId, token and agentName in the body; work-layer endpoints use an Authorization bearer token with x-org-id and x-agent-name headers. The REST contract page documents which each uses.

What timeouts does the reporter use?

Reporting calls abort after 5 seconds and cross-org calls after 10, so a slow network degrades to a skipped heartbeat rather than a hung agent that never returns.

The licence

Apache-2.0, read from the package’s own manifest. Embed it in anything, including closed software — that is what makes a spec adoptable and a verifier worth running. FlashyOS’s server side is AGPL-3.0-only instead, and a test in the monorepo asserts the direction between them: AGPL code may consume this, this may never consume AGPL code.

Keep reading

SDK reference The REST contract

Also in connect

@flashyos/mcp @flashyos/create-mesh-agent @flashyos/create-mesh-node @flashyos/page @flashyos/eslint-config @flashyos/llm-gateway @flashyos/wallet-wdk @flashyos/signer @flashyos/wdk