nanobot-runtime/skills/detach/architecture.md

Detach skill — architecture

Directory layout

~/.nanobot/workspace/tasks/
  inbox/    — tasks waiting to be picked up (written atomically from new/)
  running/  — task currently executing
  done/     — completed tasks (success)
  failed/   — completed tasks (exception or timeout)
  archive/  — tasks moved out of the active view; no longer shown by list
  new/      — atomic write staging: skill writes here, then renames into inbox/

Task lifecycle

capture (skill) → inbox/ → running/ → done/ or failed/ → archive/

1. Capture — the skill calls create-task.py, which writes the task file into new/ and atomically renames it into inbox/. This rename is the trigger for the daemon. The filename timestamp uses microsecond precision (%Y-%m-%d_%H_%M_%S_%f, e.g. 2026-06-07_15_00_00_123456-slug.md), making filename collisions impossible even for simultaneous calls with the same slug. tasks_common.py parsers accept both the old second-precision format (T-joined, e.g. 2026-06-07T150000) and the new underscore format for backward compatibility with existing task files. When --model <token> is given, the script fuzzy-resolves it to an exact preset against config.json at capture time (fail-fast in chat) and stores it in the model: frontmatter field.
2. Daemon pickup — tasks-daemon.py is started by a systemd .path unit whenever inbox/ is non-empty. It processes all files in one pass (Type=oneshot). Concurrency is handled by systemd: the service won't start again while the previous run is still live; the level-triggered .path unit re-triggers it after the run if inbox is still non-empty.
3. Execution — for each file in inbox/: move to running/, read frontmatter, call Nanobot.run(goal, session_key="detach:<stem>") with a 45-minute timeout in an isolated session. If the frontmatter carries model: <preset>, the daemon switches to it via bot._loop.set_model_preset(preset) before running (the same switch the /model chat command performs); otherwise the task runs on agents.defaults.modelPreset.
4. Completion — daemon appends ## Result and a trailing metadata block (completed, duration_seconds, status) to the file, then moves it to done/ (success) or failed/ (exception or timeout).
5. Notification — daemon sends a Telegram message to chat_id from the frontmatter (or falls back to the first allowFrom ID for non-Telegram channels).
6. Archive — user explicitly calls the archive subaction; archive-tasks.py moves selected files from done/ to archive/.

File format

Each task is a single Markdown file:

---
created: <ISO 8601>
channel: telegram | websocket | ...
chat_id: "<id>"
slug: <kebab-case>
model: <preset>          # optional; omitted → agent default
---

# Goal

<self-contained goal text>

# Constraints

- No user interaction (isolated session, no clarification questions — work with what you have).
- <optional extra constraints>

# Result

<appended by daemon after completion>

---
completed: <ISO 8601>
duration_seconds: <int>
status: done | failed

The daemon appends the # Result section and the trailing --- block; everything before that is written by create-task.py at capture time.

Scripts

Script	Role
create-task.py	Capture: writes task file, ensures queue dirs, atomically moves to inbox/; logs CREATE to detach.log
tasks-daemon.py	Long-running one-shot systemd service; executes tasks, notifies via Telegram; logs lifecycle events to detach.log
list-tasks.py	List running/, done/, failed/ (capped at 10 newest each) as a flat bullet list, one task per bullet (slug · time · age + indented goal)
read-task.py	Format and print a completed task's result
archive-tasks.py	Move tasks from done/ to archive/ (by slug or all); logs ARCHIVE to detach.log
tasks_common.py	Shared stdlib helpers: paths, parsers, formatters, model-preset resolution, shared log() → ~/.nanobot/workspace/log/detach.log

Systemd units

Two user-level units under ~/.config/systemd/user/:

• tasks-daemon.service — Type=oneshot, runs tasks-daemon.py
• tasks-daemon.path — level-triggered, watches inbox/, starts the service when non-empty