Agent runtime

Neon is a durable Flue assistant backed by local app state. The design keeps deterministic facts and mutations in actions while using the model for synthesis, triage, and next-step reasoning.

Flue agent

The display assistant owns addressable chat sessions. A new session deliberately reloads current SOUL, skills, model config, memory summaries, and repo context. Existing sessions are not silently rewritten when those inputs change.

Neondeck indexes session metadata, linked repo/watch/task context, compact summaries, stale-context badges, and audit records in app state. Cross-session references should use those summaries and metadata first; raw transcript page access remains explicit, audited, and owned by Flue.

Actions

Actions are schema-backed deterministic capabilities. Neon uses them for config updates, repo facts, GitHub PR/check facts, runtime skill lookup, memory, dashboard presets, schedules, watches, and guarded execution. Config changes should go through typed actions, not freestyle file editing.

Workflows

Bounded jobs run as Flue workflows so each run has an identity, events, output, and inspection path.

briefing
command-run
curate_learning_store
dev-doctor
fix-pr-ci
handoff_to_kilo
promote_kilo_result
reconcile_kilo_task
review-pr-for-human
review_conversation_for_learning
review_kilo_result
review_pr_batch_for_learning
scheduled-agent-instruction
scheduler-tick
summarize_kilo_session
verify_kilo_result
watch-pr

Watched-PR Autopilot uses one continuing pr-autopilot-owner agent per PR rather than a chain of transition workflows. The manual /fix-ci command remains a separate fix-pr-ci workflow.

Skills

Skills provide procedural knowledge and conventions. The built-in neondeck skill is app-owned. User runtime skills are trusted local extensions loaded from runtime-home skills/ and configured external skill roots.

Memory

Structured memory supports active user, local, and project scopes. Legacy session and watch rows may be read for compatibility, but new learning writes do not create them. Memory is current guidance for future sessions; archive history and audit events preserve what changed. See memory and learning for scopes, curation, and session-stability behavior.

Schedules and watches

The local scheduler admits real Flue workflow runs for bounded scheduled work. PR watches are deterministic pollers that invoke agent reasoning only when there is meaningful state to summarize or act on.

Scheduled tasks cover PR watches, briefings, and bounded agent instructions. Their validated triggers are persisted locally, while Flue owns each admitted workflow run.

Reports and busywork

Busywork automation writes durable local reports under the runtime home and lists them through GET /api/reports and the Reports dashboard panel. /review-pr produces PR overview and findings reports plus local Neon-origin draft comments for a human reviewer. /fix-ci writes a CI failure dossier and, when a bounded Kilo run creates commits, returns through the prepared diff review loop. /explain-ci --report writes the dossier without attempting a fix.

Reports are local artifacts served from /reports/:id. Docs-drift reports can stage a docs fix into a managed worktree, but the result still lands as a prepared diff for human review.

Scheduled tasks

Scheduled tasks are validated local records with a typed spec and an interval, one-shot, or timezone-aware cron trigger. The scheduler claims each due occurrence before dispatching a bounded Flue workflow; approval-gated actions remain approval-gated. Morning briefings use a typed profile and a persistent, non-active briefing session so a background run never replaces the dashboard's active conversation. The scheduled-task API also creates agent instructions and can pause, resume, or delete existing tasks.

Briefing orchestration persists deterministic grounding separately from the Flue transcript, dispatches the user's selected display assistant model with its complete configured MCP catalog, and settles run metadata from Flue submission observations. Assistant prose is never an application schema. MCP login or approval failures produce a candid partial briefing rather than fabricated facts or automatic approval.

External agent handoff

Same-host agents and local hooks can hand work to Neon through the CLI or the localhost-only /api/handoff/* mirror. Handoff verbs are additive: they create attributed PR watches, notifications, release watches, and optionally queue the bounded PR review workflow when handoff.allowExternalReviewQueue allows it. They do not execute commands, approve work, push branches, submit GitHub reviews, or mutate provider settings.

neondeck register-pr owner/repo#123 --from codex --note "adds retry logic" --json

curl -sS -X POST http://127.0.0.1:3583/api/handoff/register-pr \
  -H 'content-type: application/json' \
  --data '{"source":"codex","ref":"owner/repo#123","note":"adds retry logic"}'

The repository ships an Agent Skills-compatible skills/neondeck-handoff/SKILL.md. Copy that skill folder into another agent's local skill root, such as ~/.claude/skills/, or reference it from repo-level agent guidance so those agents register PRs after pushes.

Observability

neondeck records Flue observations, failed runs, workflow summaries, emitted progress data, action/tool activity, and notifications. Raw run inspection can expose prompts and tool data, so dashboard summaries stay compact and guarded.