---

name: tutorial-guide-agent-runtime description: > Nested tutorial-guide reference for lessons 4–6: init.json, lingtai-agent run, heartbeat and signal files, TUI runtime wrapping, and system prompt identity. version: 1.0.0 last_changed_at: "2026-07-18T00:00:00Z" maintenance: "If you find stale or incorrect information here, use the lingtai-issue-report skill to assemble evidence and obtain per-issue human consent before filing an issue. Never include secrets, credentials, tokens, or private paths."

Tutorial Guide — Agent Runtime Lessons

Nested tutorial-guide reference for agent runtime lessons 4–6, reached from the root tutorial-guide router. Teach live per the router's discover, don't recite rule: read the real file or run the real command before explaining it.

Lesson 4: How Agents Are Born — init.json and lingtai-agent run

Part 1: init.json

Read YOUR init.json and walk through every field you find. Do not recite a list of fields — read the file and explain what is there. The human sees the real structure.

Key patterns to explain:

• The _file convention: live init fields like covenant, pad, comment, base_prompt take inline text or a <field>_file path to a shared file. (Older fields such as principle, procedures, brief, soul, and the legacy prompt are migrated by the kernel but no longer seeded here.) Note: there is no seed field for the agent's character in init.json — character is durable state the agent authors for itself after creation, managed via system/lingtai.md / psyche, not written into init.json.
• manifest contains: llm, agent_name, language, capabilities, admin, etc.
• addons connects to external messaging services.
• env_file for secrets.

Part 2: lingtai-agent run

Explain the boot sequence: read init.json → load env → resolve venv → build Agent → clean stale signals → install signal handlers → start in ASLEEP state → agent.start() blocks on shutdown.

Emphasize: the agent is a long-running Python process. It does not exit after one task.

Part 3: Heartbeat and signal files

Show your own .agent.heartbeat — read it, wait a second, read again to show the timestamp changes. Explain the signal files: .interrupt, .suspend, .sleep, .prompt.

Lesson 5: The TUI — How lingtai-tui Wraps the Agent Runtime

Explain: lingtai-tui is a Go frontend, not the agent. It creates agents (writes init.json), launches them (python -m lingtai run), monitors them (.agent.heartbeat, .agent.json), controls them (signal files), and manages communication (reads/writes mailbox/).

Draw the architecture diagram (TUI ↔ filesystem ↔ agent process).

Explain: you do not need the TUI to run an agent. A valid init.json + lingtai-agent run is sufficient.

Walk through TUI-specific features: preset system, setup wizard, slash commands (read from ~/.lingtai-tui/commands.json to list them), keyboard shortcuts (ctrl+o, ctrl+e), text selection (Option/Alt+drag), network visualization, human directory.

Mention that headless CLI management commands exist; Lesson 10 walks through lingtai-tui --help in full, so leave the enumeration for then.

Lesson 6: Identity — How the System Prompt Works

Read your own system/system.md and show the human the fully assembled system prompt.

To discover the section order: read the source code. Run:

python3 -c "
try:
    from lingtai.kernel.prompt import SystemPromptManager
except ImportError:
    from lingtai_kernel.prompt import SystemPromptManager
print(SystemPromptManager._DEFAULT_ORDER)
"

This gives you the real, current section render order. Walk through each section in that order, explaining what it is and whether it's protected (host-written) or editable (agent-written). Read the actual file for each section under system/ to show real content.

Key concepts to explain:

• Protected sections (principle, covenant, rules, procedures) cannot be changed by the agent
• Editable sections (identity/lingtai, pad) are how the agent evolves
• Brief is externally maintained by the secretary
• Skills are discovered at runtime
• Comment is app-level instructions (like your tutorial instructions)

Emphasize that identity/character (system/lingtai.md) is the key to individuality — it's how agents develop unique personalities through experience.