qflush

qflush is the main Funesterie orchestrator.

It combines a CLI, a long-running daemon, ephemeral memory endpoints, NPZ helpers, service supervision hooks and integrations with modules such as Rome, Spyder, Bat, Freeland and Nezlephant.

Current package line

• npm package: @funeste38/qflush
• current repo version: 4.0.16
• daemon entry point: src/daemon/qflushd.ts

What qflush is good at

• running a local or hosted orchestration daemon
• exposing admin and memory endpoints to A11 or other tools
• managing NPZ-oriented flows and Rome indexing helpers
• bridging telemetry, Redis-backed state and lightweight service supervision

Install

npm install @funeste38/qflush

Quick start

npm install
npm run build
npm start

Or with Railway-compatible scripts:

npm run railway:build
npm run railway:start

Repository map

• src/daemon/ -> HTTP daemon and operational endpoints
• src/rome/ -> rule engine, indexing and action logic
• src/commands/ -> CLI commands
• src/utils/ -> Redis, secrets, fetch, HMAC, memory and path helpers
• tests/ -> Vitest coverage for the critical runtime
• runner-package/ -> lightweight runner flavor for CI or reduced environments

Important runtime variables

• QFLUSHD_PORT or PORT -> daemon port
• NEZ_ADMIN_TOKEN -> protects admin and memory endpoints
• REDIS_URL / QFLUSH_REDIS_URL -> Redis backend for persistent and ephemeral state
• QFLUSH_ENABLE_REDIS / QFLUSH_DISABLE_REDIS -> Redis toggle
• QFLUSH_DISABLE_COPILOT, QFLUSH_TELEMETRY, QFLUSH_ENABLE_COPILOT -> telemetry controls
• QFLUSH_COPILOT_TRANSPORTS -> file, webhook, sse
• QFLUSH_COPILOT_WEBHOOK_URL -> outgoing webhook target
• QFLUSH_LOG_FORMAT -> pretty, plain, json

Ephemeral memory

qflush exposes a TTL-based ephemeral memory layer that can run:

• on Redis when configured
• in local memory as fallback

Main endpoints:

• /api/memory/ephemeral/status
• /api/memory/ephemeral/set
• /api/memory/ephemeral/get
• /api/memory/ephemeral/list
• /api/memory/ephemeral/delete
• /api/memory/ephemeral/clear
• /api/memory/ephemeral/touch

Example:

curl -X POST http://127.0.0.1:43421/api/admin/run \
  -H "Authorization: Bearer changeme" \
  -H "Content-Type: application/json" \
  -d "{\"flow\":\"a11.memory.ephemeral.v1\",\"payload\":{\"op\":\"set\",\"scope\":\"user:jeff\",\"key\":\"last_topic\",\"value\":\"A11\",\"ttlSec\":1800}}"

Railway notes

Recommended minimum for a stable hosted instance:

• QFLUSH_DISABLE_COPILOT=0
• QFLUSH_ENABLE_COPILOT=1
• QFLUSH_TELEMETRY=1
• QFLUSH_COPILOT_TRANSPORTS=file,webhook
• QFLUSH_COPILOT_WEBHOOK_URL=... only if you really want alerts
• QFLUSH_DISABLE_REDIS=0 only when Redis is actually configured
• NEZ_ADMIN_TOKEN=...

On hosted ESM builds, qflush now loads ioredis through a compatible Node module bridge instead of silently falling back to memory because require was unavailable.

Development

npm install
npm run build
npm test
npm run typecheck

Good next improvements

• formal plugin API for external module registration
• clearer structured telemetry output per flow
• first-class dashboards for daemon state and memory usage
• more real-world fixtures around A11 and multi-service supervision

Related packages

• @funeste38/qflush-runner for lightweight CI usage
• @funeste38/rome for workspace and process control
• @funeste38/nezlephant for OC8 payload transport
• @funeste38/freeland for value normalization
• @funeste38/bat for adaptive runtime behaviour