FFT_nano
Developer Docs

Comprehensive, implementation-anchored documentation rebuilt from src/, container/agent-runner/src/, and runtime scripts.

Node.js >= 20 TypeScript Host LOC: 9,858 25 Module References Code-Accurate
Guide Index Module Reference

Quickstart

Read In This Order

  1. Architecture
  2. Runtime Message Flow
  3. Container Runtime
  4. Module Index
Validate Runtime
npm run typecheck
npm test
npm run validate:skills

Documentation Coverage

AreaCoverage
Host RuntimeAll modules under src/*.ts documented
Container Runtimecontainer/agent-runner/src/*.ts deep-dive included
Commands and IPCTelegram command surface, task/action IPC payloads documented
Storage ContractsSQLite tables, FTS index, JSON snapshots, farm-state files documented
Security BoundariesMain/non-main gates, mount allowlist, path traversal guards documented
Operational ScriptsSetup/start/farm/release script behavior documented
Source-of-Truth Rule
If docs and code diverge, code wins. This docs set is built to minimize that divergence by referencing concrete modules and contracts.

Architecture Snapshot

Single host process orchestrates message ingress, persistence, containerized agent execution, scheduler loops, and IPC action/task handling.

FileRole
src/index.tsMain orchestrator (message loops, commands, routing, lifecycle)
src/container-runner.tsMount/env policy + container execution + result parsing
src/db.tsSQLite schema + message/task persistence + FTS transcript search
src/task-scheduler.tsDue-task polling and scheduled task execution
src/telegram.tsTelegram poll/send/download abstraction
container/agent-runner/src/index.tsIn-container pi runtime bridge

Runtime Flow

  • Ingress via Telegram and/or WhatsApp
  • Per-chat queue policy applied (collect|interrupt|followup|steer|steer-backlog)
  • Prompt built from missed messages since last agent interaction
  • Container run launched with per-chat overrides (model/provider/think/reasoning)
  • Result streamed or sent final, then timestamps and usage counters updated

Full details: Runtime Message Flow

Config and Environment

High-Impact Env Vars
TELEGRAM_BOT_TOKEN=
WHATSAPP_ENABLED=0|1
CONTAINER_RUNTIME=auto|apple|docker
FFT_NANO_MAIN_WORKSPACE_DIR=~/nano
MEMORY_RETRIEVAL_GATE_ENABLED=1
MEMORY_TOP_K=8
FARM_STATE_ENABLED=true|false
FARM_MODE=demo|production
HA_URL=http://localhost:8123
HA_TOKEN=...

Full reference: Configuration and Environment Variables

IPC Contracts

Per-group IPC namespace at data/ipc/<group>/ mounted to /workspace/ipc.

Message IPC
{
  "type": "message",
  "chatJid": "telegram:123456",
  "text": "status update"
}
Task IPC
{
  "type": "schedule_task",
  "prompt": "Check greenhouse readings",
  "schedule_type": "cron",
  "schedule_value": "0 * * * *",
  "context_mode": "isolated",
  "groupFolder": "main"
}

Full payload contracts: IPC Contracts

Memory System

  • Canonical memory file is MEMORY.md per group
  • SOUL.md is identity/policy context, not compaction log store
  • Retrieval-gated memory context is built lexically from group + global memory
  • Transcript episodic memory is powered by SQLite FTS5

Full behavior: Memory System

Farm Mode and Home Assistant

  • Fast/medium/slow collector loops write farm-state ledgers
  • Farm actions are allowlisted and main-chat-only
  • Production mode blocks control actions until profile validation passes

Full behavior: Farm Mode and Home Assistant

Security Model

  • Container isolation for all agent execution
  • External mount allowlist at ~/.config/fft_nano/mount-allowlist.json
  • Main vs non-main authorization gates on commands and IPC
  • Path traversal protection for memory actions

Full controls: Security Model

Full Guide Index

GuideScope
01-architectureSystem architecture and startup topology
02-runtime-message-processingMessage-to-run flow with queue and delegation logic
03-container-runtimeRuntime selection, mounts, env passthrough, container execution
04-config-envCode-backed env/config reference
05-telegramTelegram API integration, commands, media handling
06-whatsappBaileys connection/auth/runtime behavior
07-scheduler-and-tasksScheduler loop, task schema, control commands
08-ipc-contractsMessage/task/action IPC payload contracts
09-memory-systemMemory retrieval/search/compaction model
10-farm-modeCollector loops, farm actions, production gate
11-security-modelIsolation and authorization controls
12-coding-delegationDelegation triggers, constraints, subagent commands
13-data-modelsType contracts and persistence structures
14-testing-releaseValidation and release checks
15-agent-runnerIn-container runtime internals
16-scripts-referenceOperational script reference

All Source Module References

One page per host module under src/*.ts with exported API signatures and env references.

Core

index.ts
config.ts
types.ts
logger.ts
utils.ts

Container

container-runner.ts
container-runtime.ts
apple-container.ts
mount-security.ts

Chat

telegram.ts
telegram-format.ts
whatsapp-auth.ts
coding-delegation.ts

Data

db.ts
task-scheduler.ts
singleton-lock.ts

Memory

memory-paths.ts
memory-maintenance.ts
memory-retrieval.ts
memory-search.ts
memory-action-gateway.ts

Farm and Skills

home-assistant.ts
farm-state-collector.ts
farm-action-gateway.ts
pi-skills.ts

Master list: module-index.html

Scripts and Release

Primary Script Commands
./scripts/setup.sh
./scripts/start.sh start
./scripts/start.sh dev telegram-only
./scripts/farm-bootstrap.sh --mode demo
./scripts/farm-bootstrap.sh --mode production
npm run release-check

Details: Scripts Reference and Testing and Release

Status: Old visual style restored. New comprehensive content and references are now wired into this styled docs hub.