@fibscope/agent 0.1.0

package/.env.example

@@ -0,0 +1,7 @@
+# fibscope agent defaults for a node owner's machine.
+# The Fibscope endpoint is built into the published agent.
+FIBKEY=replace-with-token-issued-by-platform
+FIBSCOPE_AGENT_CHAIN=testnet
+FIBSCOPE_AGENT_FIBER_RPC_URL=http://127.0.0.1:8227
+FIBSCOPE_AGENT_PUSH_INTERVAL_MS=15000
+FIBSCOPE_AGENT_PUBLIC_PROFILE=false

package/PUBLISH.md

@@ -0,0 +1,27 @@
+# Publish Checklist
+
+Run from the repository root unless noted.
+
+```powershell
+npm --prefix packages/agent run check
+npm --prefix packages/agent run pack:dry-run
+cd packages/agent
+npm publish --dry-run --access public
+npm login
+npm publish --access public
+```
+
+After publish:
+
+```powershell
+npx @fibscope/agent --help
+npx @fibscope/agent init
+npx @fibscope/agent status
+```
+
+Notes:
+
+- Package name: `@fibscope/agent`
+- Commands: `agent` and `fibscope-agent`
+- Reads config from `agent/.env`, `.env`, or `.fiber/agent.json` in the current working directory.
+- FNN RPC should stay bound to localhost.

package/README.md

@@ -0,0 +1,123 @@
+# Fibscope Agent
+
+Independent Node.js ESM agent for Fiber node owners.
+
+It runs beside an existing Fiber node, collects local Fiber state, builds an observability report, and pushes that report to Fibscope.
+
+```text
+Fiber RPC -> Agent -> Fibscope HTTPS endpoint
+```
+
+The agent is the only component that talks to local Fiber RPC. Fibscope never reaches into the node owner's machine; it only receives pushed reports from this agent.
+
+## Config
+
+Local personal-development defaults live in `agent/.env`:
+
+```text
+FIBKEY=raw-token-issued-by-platform
+FIBSCOPE_AGENT_CHAIN=testnet
+FIBSCOPE_AGENT_FIBER_RPC_URL=http://127.0.0.1:8247
+FIBSCOPE_AGENT_PUSH_INTERVAL_MS=15000
+FIBSCOPE_AGENT_PUBLIC_PROFILE=false
+FIBSCOPE_AGENT_OVERWRITE_NODE_REGISTRATION=false
+```
+
+This file belongs to the node owner's machine. The Fibscope service endpoint is built into the published agent, so node owners do not need to configure a report URL.
+
+The agent also supports `.fiber/agent.json`:
+
+```json
+{
+  "agentToken": "raw-token-issued-by-platform",
+  "chain": "testnet",
+  "fiberRpcUrl": "http://127.0.0.1:8247",
+  "peerAddress": "/ip4/127.0.0.1/tcp/8248",
+  "pushIntervalMs": 15000,
+  "publicProfileEnabled": true,
+  "overwriteNodeRegistration": false,
+  "publicFields": {
+    "node": true,
+    "peers": true,
+    "channels": true,
+    "liquidity": true,
+    "diagnostics": true,
+    "health": true,
+    "metrics": true,
+    "alerts": true
+  }
+}
+```
+
+`peerAddress` is the Fiber dial address advertised to Fibscope for public routing and channel creation. For local duo development this is usually a loopback multiaddr like `/ip4/127.0.0.1/tcp/8228`; for an internet-facing public node, set it to an address other nodes can actually dial.
+
+## Commands
+
+```powershell
+npm run agent:init
+npm run agent:start
+npm run agent:once
+npm run agent:status
+```
+
+Direct usage:
+
+```powershell
+node packages/agent/index.mjs init
+node packages/agent/index.mjs start
+node packages/agent/index.mjs once
+node packages/agent/index.mjs status
+```
+
+## Push Payload
+
+The agent pushes to `POST /agent/v1/report` with:
+
+```json
+{
+  "agentVersion": "0.1.0",
+  "chain": "testnet",
+  "collectedAt": 1710000000000,
+  "node": {},
+  "peers": [],
+  "channels": [],
+  "liquidity": {},
+  "diagnostics": [],
+  "health": {},
+  "metrics": {},
+  "alerts": []
+}
+```
+
+Fibscope authenticates this with `x-agent-token`. This is an agent key for local node reporting, not the external application API key that apps will use for quote and payment execution.
+
+Before the first push, the agent registers the local Fiber node with `POST /agent/v1/register`. That saves the node owner, Fiber node id, display name, chain, public profile setting, and the latest local node details in the hosted database. If the agent key is already attached to a different registered Fiber node, set `overwriteNodeRegistration` to `true` only when you intentionally want this agent to replace that old node binding.
+
+## Resilience
+
+Collection and transmission are independent loops:
+
+- collection runs every `pushIntervalMs`
+- transmission retries retained reports independently
+- failed pushes stay in memory
+- backoff doubles up to 5 minutes
+- `409 Conflict` is treated as a stale report response
+
+The local status file is `.fiber/agent-status.json`.
+
+## NPM Usage
+
+```powershell
+npm install -g @fibscope/agent
+agent init
+agent start
+```
+
+Or run without a global install:
+
+```powershell
+npx @fibscope/agent init
+npx @fibscope/agent start
+```
+
+The package reads `agent/.env`, `.env`, or `.fiber/agent.json` from the directory where you run the command. Keep FNN RPC local, for example `http://127.0.0.1:8227`.