Roadmap

This is the single source for delivery status and priorities. Statuses reflect the code in the repository, not intentions. Architecture details live in architecture.md.

Legend: [x] done, [~] partially done, [ ] not started.

0. Release 1.0.0 (target 2026-10-27)

1.0.0 makes the core dependable: a flow.md written for 1.0 keeps running on every 1.x version. The GitHub milestones (not the phase numbers below) track the work.

Phase 5 (developer tools: kinenix graph, VS Code extension) comes after 1.0.0.

1. Next Priorities

Ordered so that safety and predictable runtime behavior come before new distributed features.

1.4 Continuous Integration

GitHub Actions workflow .github/workflows/ci.yml runs on pushes and pull requests to main and dev:

• Python 3.10 and 3.14 on Ubuntu, and Python 3.10 on Windows.
• Installs kinenix-core, kinenix-worker, kinenix-studio, and kinenix-hub with development dependencies.
• Runs every pytest suite, including kinenix-hub/tests.
• Builds the Studio frontend with npm ci and npm run build.
• CI status badge in the README.
• Repository rules checked by tests: every flow validates, documented action parameters match the code, and no emojis anywhere.
• Formatting, linting, type checking, dependency vulnerability checks, and JSON schema validation of the flows in flows/.
• [~] Publish kinenix, kinenix-hub, and kinenix-worker from a tagged release with Trusted Publishing (release.yml, docs/releasing.md); CI builds, checks, and installs the packages on every pull request. Waiting for the first release.

1.5 Hub Hardening

• Protect the dashboard page and read endpoints (HTTP Basic Auth, localhost-only when unset).
• Remove the permissive CORS policy; the dashboard is served same-origin.
• Default the bind host to 127.0.0.1, requiring an explicit opt-in to listen on the network.
• Escape all worker-provided text in the dashboard (XSS), with a static check and a real-browser test.
• Content-Security-Policy header for the dashboard (needs the inline onclick handlers moved to script).
• Run AI failure analysis in the background so telemetry ingestion does not wait on the LLM.
• Document an HTTPS reverse proxy setup (e.g. Caddy or nginx).

1.6 Persistent Studio Sessions and Debugging

• Maintain one Playwright browser and context per explicit Studio session.
• Add a "run this step" API that executes against the retained browser state.
• Stream interpreter events: step state, logs, errors, variable snapshots, screenshots.
• Add breakpoints and an element picker that returns robust selector candidates.
• Define session ownership, expiration, cleanup, and isolation so sessions do not leak browser processes.

1.7 Worker WebSocket Protocol and Hub Dispatch

Hub -> versioned job bundle -> Worker (WebSocket) -> kinenix-core executes flow
                                              |
                                              +-> status, logs, metrics, screenshots -> Hub

• Authenticate workers and authorize job delivery (per-worker credentials).
• Require job acknowledgement and use idempotency keys to prevent duplicate execution after reconnects.
• Support reconnects, cancellation, timeouts, heartbeats, and clear job state transitions.
• Package and version bundles so a worker runs the intended immutable artifact.
• Upload execution artifacts safely and retain structured audit logs.
• Follow the Hybrid Protocol in architecture.md.

2. Phases

Phase 1: Core Engine (kinenix-core) - Done

• Flow JSON schema and Pydantic v2 models
• Interpreter, execution context, and ${var} evaluator (no eval)
• Actions: Web (Playwright), Excel/CSV, file system, HTTP, email, logic, flow control
• Error handling: on_error with continue, retry, and fallback_step_id; failure screenshots
• Hierarchical structured logging (logs/<flow>/<date>/<HHMMSS>_<status>.json)
• CLI and smart flow resolver (kinenix list, kinenix run <flow>)
• Project bundles (flow.call, @shared/, config.json, .env)
• flow.md authoring format
• Local AI actions: ai.prompt, ai.extract (Ollama), ai.decide (OpenThai-SystemOne)
• flow.md is the only flow file: kinenix run and the worker read it directly, kinenix compile prints the compiled form, kinenix export-md converts old JSON flows; step headings without an action and flows without steps are reported (flow.json dropped after a comparison with YAML on bot_fx_rate)
• Flow validation (kinenix validate): unknown actions and ignored parameters, with suggestions
• Business exceptions with flow.fail (recorded as Business, never retried); web.click waits for a response; web.get_table
• email.send through any SMTP provider (Gmail, Microsoft 365, company servers), tested with a local fake SMTP server
• Example flow bot_fx_rate: Bank of Thailand transfer rates to CSV and email, verified against the BOT data
• file.zip and file.unzip: pack a run's output for an email attachment; extraction refuses entries that point outside the destination
• file.list (loop over the files in a folder, newest first), file.read_text and file.write_text (text, lines, JSON, append, Thai legacy encodings), file.create_folder; boolean parameters given as text in config ("false") are read correctly by all file actions
• Subflows written as .md (compiled when called), sharing the bundle's config and folder; @shared components keep their own unless inherit_config: true; kinenix validate follows subflows and checks inputs names; the hello example calls a subflow
• date.calc: today or a given date, shifted by days, weeks, months, or years and snapped to the start or end of a week, month, or year; bot_fx_rate reports the previous month by default instead of fixed dates

Phase 2: Studio (kinenix-studio) - Paused

Paused on 2026-10-08. Flows are written as flow.md from a requirements.md with an AI assistant (kinenix init), so a visual flow editor duplicates that work while adding a React and FastAPI application to maintain. The hardest part of authoring, finding selectors on real pages, moves to a kinenix record command built on Playwright's recorder (priority 7 above). The code stays in the repository and in CI, is not published, and receives no new features until this decision is revisited.

• FastAPI backend: flow discovery, read/save with schema validation, step update, action metadata, run
• Path containment to flows/ and restricted CORS
• React/Vite 3-column UI (step timeline, inspector, context panel) served by the backend
• Persistent browser session and single-step execution (POST /api/session/step)
• Element picker with multi-layer selectors (role/text, CSS, XPath)
• Live debugger over WebSocket: step highlighting, variable watcher, error screenshot viewer
• AI prompt bar for natural-language flow generation
• Tauri desktop shell

Phase 3: Hub (kinenix-hub) - In progress

• Renamed from Orchestrator to Hub; old command, flags, environment variables, and settings file still work (see hub.md)
• FastAPI service with heartbeat and telemetry ingestion over HTTP
• Execution and worker storage via SQLAlchemy (SQLite default, DATABASE_URL for others)
• Web dashboard for workers and executions, with per-execution step details
• Command line: first-run setup saved to ~/.kinenix/hub.env, kinenix hub status, logs, setup, show-key, and rich output
• Default database in ~/.kinenix/hub.db, outside the source tree
• Schema migrations applied at start (built-in runner, schema_version table, no extra dependency) and SQLite WAL mode, so existing databases upgrade in place and readers do not block workers
• Run records for people and AI: every step (step_results) and every failure (failures, also continued ones) with path, subflow, line, loop item, retries, and how it was handled; a Markdown run report per run; views v_runs, v_failures, v_steps; runs stored earlier are filled in from their logs; data dictionary in hub_data.md, checked by a test
• kinenix connect URL: asks for the worker key, checks it against the Hub, and saves the Hub in ~/.kinenix/kinenix.env for kinenix run and kinenix-worker; kinenix hub setup offers the same for runs on the Hub machine, so no environment variables are needed
• kinenix hub report [ID] --flow NAME: the run report of a flow's latest run (name or part of it, --limit N for more), and kinenix hub logs --flow NAME for its steps
• kinenix hub query: read-only questions to the Hub database from the terminal, on the Hub machine or over HTTP (--url): views or tables with --since, --flow, --worker, --status, --filter, or one SQL SELECT; --list and --describe from the data dictionary; table, JSON, CSV, and Markdown output; user views from ~/.kinenix/hub_views/custom_*.sql
• AI failure classification with rule-based fallback
• Worker API key authentication
• Dashboard authentication (HTTP Basic Auth)
• No CORS policy and localhost-only default bind address
• Background AI analysis and HTTPS deployment guide (see 1.5)
• PostgreSQL + Redis job queue
• Business ROI dashboard: hours saved, cost saved, transaction audit trail
• Alerts and daily digests (LINE Messaging API first, then Teams and Email)
• [~] Natural-language questions about jobs and workers with a local model (see ask_router.md)

Phase 4: Worker (kinenix-worker) - In progress

• kinenix-worker run, watch (file trigger), schedule (interval), daemon (multi-trigger config)
• Optional per-job sandbox workspace (~/.kinenix/workspaces/<job_id>)
• Verified on Raspberry Pi 4 (ARM64) with setup script; re-verified on 2026-10-05 after the rename to Hub: heartbeats as a systemd service and the bot_fx_rate flow run by a cron trigger, reported to the Hub
• Heartbeat sender to the Hub (kinenix-worker ping, busy/online/offline status), with rich output
• systemd service installed by the setup script (install_service.sh), starts the daemon at boot
• Cron schedules ("cron": "0 8 1 * *" in triggers.json, kinenix-worker schedule --cron)
• WebSocket job client (see 1.7)
• Bundle packaging (.kinpkg), download, and local cache
• Real-time log and screenshot streaming

Phase 5: Desktop Automation and Public Release - Not started

• Windows desktop automation (uiautomation / UIA)
• Credential vault for flow secrets
• Docker Compose one-command deployment
• Community quickstart documentation (quickstart.md)
• kinenix init "Task name": new project for the requirements-to-AI-to-flow.md workflow (requirements.md, AGENTS.md for the assistant, .env.example); kinenix init --example with packaged examples (hello, bot_fx_rate, rpachallenge); kinenix actions lists actions and their parameters
• User flows live in a flows folder outside the Kinenix repository (default ~/kinenix-flows, asked on the first kinenix init, optional git repository, kinenix flows-dir, KINENIX_FLOWS_DIR); kinenix run NAME and worker triggers find flows there by name

Phase 6: Advanced Local Agentic Capabilities - Not started

• Self-healing UI selectors with DOM fallback matching
• Studio copilot for natural-language flow generation and error diagnosis
• GitOps release pipeline to Hub and workers