skills.rest
Lingtai-AI
Lingtai-AIOFFICIAL
Explore all skills by this author →
GitHub

portal-guide-lifecycle-and-recording

Explains portal agent lifecycle states, heartbeat staleness, and topology tape recording behavior.

692|60|Updated Mar 15, 2026
Search Tags:#topology#JSONL#heartbeat#reconstruction#Portal#Lifecycle#Agent Monitoring
One-click install
npx skills add https://github.com/Lingtai-AI/lingtai --skill portal-guide-lifecycle-and-recording
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: portal-guide-lifecycle-and-recording
Source: https://github.com/Lingtai-AI/lingtai/tree/main/tui/internal/preset/skills/lingtai-portal-guide/reference/lifecycle-and-recording
Command: npx skills add https://github.com/Lingtai-AI/lingtai --skill portal-guide-lifecycle-and-recording

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It clarifies how the LingTai portal interprets agent lifecycle states and liveness, and how it records and reconstructs network topology history, so operators can correctly diagnose agent status and topology data.

Core Features & Use Cases

  • Lifecycle State Reference: Documents the five agent states (ACTIVE, IDLE, STUCK, ASLEEP, SUSPENDED) and how heartbeat staleness affects liveness without rewriting manifest state.
  • Recording Behavior: Explains the 3-second BuildNetwork polling loop that appends JSONL lines to topology.jsonl.
  • Reconstruction Logic: Covers tape rebuild from replay chunks, the reconstruct.progress file, the /api/topology/progress endpoint, and manual POST /api/topology/rebuild.
  • Use Case: When an agent shows as not alive but its manifest still says ACTIVE, consult this reference to understand that a stale heartbeat only clears the Alive flag rather than rewriting stored state.

Quick Start

Ask the portal guide to explain why an agent shows as not alive while its lifecycle state remains ACTIVE.

Frequently Asked Questions about portal-guide-lifecycle-and-recording

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does an agent show as not alive but still have ACTIVE state?▼

A stale or missing heartbeat only clears the AgentNode.Alive flag; it does not rewrite the stored lifecycle state in .agent.json. An ACTIVE agent with a stale heartbeat keeps its real state and is simply reported as not alive.

How does the portal determine agent liveness?▼

BuildNetwork calls IsAlive with a threshold resolved from the LINGTAI_AGENT_ALIVE_THRESHOLD_SEC environment variable, defaulting to 10 seconds. Missing, malformed, zero, or negative values fall back to the default.

What are the agent lifecycle states in the LingTai portal?▼

The portal uses five states: ACTIVE (running and processing), IDLE (running but waiting), STUCK (error or unresponsive), ASLEEP (sleep mode), and SUSPENDED (process not running per kernel or manifest).

How does the portal record network topology history?▼

On launch, a background goroutine calls BuildNetwork every 3 seconds and appends each result as a JSONL line to topology.jsonl. This tape grows indefinitely and serves as the topology history.

How do I rebuild the topology tape manually?▼

Send a POST request to /api/topology/rebuild, which reconstructs from source data and rewrites the replay chunks. Automatic reconstruction on startup uses replay chunks and exposes progress via /api/topology/progress.

Related Skills

Explore More Software Engineering Skills→
Lingtai-AILingtai-AI
621

tutorial-guide

Guide learners through a 12-lesson tutorial on Lingtai with live exploration.

Official
Advanced
parcadeiparcadei
3.9k

debug

Diagnose issues by investigating logs, database state, and git history.

Community
Intermediate
Lingtai-AILingtai-AI
621

lingtai-portal-guide

Explain LingTai portal internals, topology recording, and .portal directory structure.

Official
Intermediate
nteractnteract
158

execution-pipeline

Traces notebook cell execution from MCP tool invocation through daemon and kernel to resolve failures.

Official
Advanced