@virtengine/openfleet 0.25.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2018 DET-IO Pty. Ltd..
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,500 @@
+# @virtengine/openfleet
+
+Autonomous supervisor for AI coding workflows.
+
+`openfleet` watches task execution, routes work across agent executors, handles retries/failover, automates PR lifecycle, and keeps you in control through Telegram (with optional WhatsApp and container isolation).
+
+---
+
+## Why openfleet
+
+AI coding agents are fast, but unattended loops are expensive:
+
+- silent failures
+- repeated retries with no progress
+- stale worktrees and merge drift
+- disconnected notifications
+
+`openfleet` is the control plane that keeps delivery moving:
+
+- task routing and executor failover
+- monitored orchestration and auto-recovery
+- conflict/PR lifecycle automation
+- live bot control (`/status`, `/tasks`, `/pause`, `/resume`, etc.)
+
+---
+
+## Install
+
+```bash
+npm install -g @virtengine/openfleet
+```
+
+Requires:
+
+- Node.js 18+
+- git
+- Linux, macOS, and Windows are fully supported
+- Shell runtime for your selected orchestrator wrapper:
+  - Bash for `.sh` wrappers
+  - PowerShell (`pwsh`) for `.ps1` wrappers
+- GitHub CLI (`gh`) recommended
+
+---
+
+## Quick start
+
+```bash
+cd your-repo
+openfleet
+```
+
+First run launches setup automatically.
+
+You can also run setup directly:
+
+```bash
+openfleet --setup
+```
+
+---
+
+## Setup modes (new)
+
+The setup wizard now starts with two modes:
+
+- **Recommended**
+  - prompts only for important decisions (project identity, executor preset/model profile, AI provider, Telegram, board/execution mode)
+  - keeps advanced knobs on proven defaults
+  - writes a standardized `.env` based on `.env.example` so all options remain documented
+  - auto-generates repository `.vscode/settings.json` with Copilot agent/subagent/MCP/autonomous defaults
+
+- **Advanced**
+  - full control over repository layout, failover/distribution, hook targets/overrides, orchestrator path, VK wiring details, and optional channels
+
+---
+
+## How openfleet can run
+
+### 1) Standard foreground supervisor
+
+```bash
+openfleet
+```
+
+### 2) Daemon mode
+
+```bash
+openfleet --daemon
+openfleet --daemon-status
+openfleet --stop-daemon
+```
+
+### 3) Startup service (auto-start on login)
+
+```bash
+openfleet --enable-startup
+openfleet --startup-status
+openfleet --disable-startup
+```
+
+### 4) Interactive shell mode
+
+```bash
+openfleet --shell
+```
+
+### 5) Sentinel companion mode (Telegram watchdog)
+
+```bash
+openfleet --sentinel
+openfleet --sentinel-status
+openfleet --sentinel-stop
+```
+
+---
+
+## Execution architecture modes
+
+Configured by `EXECUTOR_MODE`:
+
+- `internal` (recommended)
+  - tasks run through internal agent pool in monitor process
+- `vk`
+  - task execution delegated to VK orchestrator flow
+- `hybrid`
+  - internal + VK behavior for mixed/overflow scenarios
+
+Task board backend (`KANBAN_BACKEND`):
+
+- `internal` - local task-store source of truth (default)
+- `vk` - Vibe-Kanban adapter
+- `github` - GitHub Issues with shared state persistence
+- `jira` - Jira Issues with status/shared-state parity
+
+Sync policy (`KANBAN_SYNC_POLICY`):
+
+- `internal-primary` - internal task-store remains source of truth (default)
+- `bidirectional` - external status changes may update internal tasks
+
+Autonomous runtime defaults:
+
+- Copilot shell runs with experimental mode + allow-all + no-ask-user by default
+- Codex config enforces critical feature flags (`child_agents_md`, `memory_tool`, collaboration)
+- Setup configures common MCP servers automatically (`context7`, `sequential-thinking`, `playwright`, `microsoft-docs`)
+
+Experimental autonomous backlog replenishment:
+
+- `INTERNAL_EXECUTOR_REPLENISH_ENABLED=true|false`
+- `INTERNAL_EXECUTOR_REPLENISH_MIN_NEW_TASKS=1|2`
+- `INTERNAL_EXECUTOR_REPLENISH_MAX_NEW_TASKS=1..3`
+- `PROJECT_REQUIREMENTS_PROFILE=simple-feature|feature|large-feature|system|multi-system`
+
+**GitHub adapter enhancements:**
+The GitHub Issues adapter now supports multi-agent coordination via structured state persistence:
+
+- Claim tracking with `codex:claimed`, `codex:working`, `codex:stale` labels
+- Heartbeat mechanism to detect stale/abandoned claims
+- Task exclusion via `codex:ignore` label
+- Structured comments with JSON state for agent coordination
+
+See [KANBAN_GITHUB_ENHANCEMENT.md](./KANBAN_GITHUB_ENHANCEMENT.md) for details.
+
+### GitHub Projects v2 backend (Phase 1 + 2)
+
+`openfleet` now supports GitHub Projects v2 as a first-class kanban source and sync target:
+
+- Phase 1 (read): read tasks directly from a Projects v2 board (`GITHUB_PROJECT_MODE=kanban`)
+- Phase 2 (write): sync task status updates back to the board `Status` field
+- Bidirectional mapping between codex statuses and project status options
+- Safe fallback to issues mode when project metadata is missing or unavailable
+
+Enable with env config:
+
+```env
+KANBAN_BACKEND=github
+GITHUB_PROJECT_MODE=kanban
+GITHUB_PROJECT_OWNER=your-org-or-user
+GITHUB_PROJECT_NUMBER=3
+GITHUB_PROJECT_AUTO_SYNC=true
+```
+
+Status mapping overrides (optional):
+
+```env
+GITHUB_PROJECT_STATUS_TODO=Todo
+GITHUB_PROJECT_STATUS_INPROGRESS=In Progress
+GITHUB_PROJECT_STATUS_INREVIEW=In Review
+GITHUB_PROJECT_STATUS_DONE=Done
+GITHUB_PROJECT_STATUS_CANCELLED=Cancelled
+```
+
+Projects v2 docs:
+
+- [GITHUB_PROJECTS_V2_QUICKSTART.md](./GITHUB_PROJECTS_V2_QUICKSTART.md)
+- [GITHUB_PROJECTS_V2_API.md](./GITHUB_PROJECTS_V2_API.md)
+- [GITHUB_PROJECTS_V2_MONITORING.md](./GITHUB_PROJECTS_V2_MONITORING.md)
+- [GITHUB_PROJECTS_V2_IMPLEMENTATION_CHECKLIST.md](./GITHUB_PROJECTS_V2_IMPLEMENTATION_CHECKLIST.md)
+
+**Jira adapter parity config:**
+Jira supports the same openfleet status vocabulary and shared-state fields,
+with explicit mapping via env vars:
+
+```env
+KANBAN_BACKEND=jira
+JIRA_BASE_URL=https://your-domain.atlassian.net
+JIRA_EMAIL=you@example.com
+JIRA_API_TOKEN=***
+
+JIRA_STATUS_TODO=To Do
+JIRA_STATUS_INPROGRESS=In Progress
+JIRA_STATUS_INREVIEW=In Review
+JIRA_STATUS_DONE=Done
+JIRA_STATUS_CANCELLED=Cancelled
+
+JIRA_CUSTOM_FIELD_OWNER_ID=customfield_10042
+JIRA_CUSTOM_FIELD_ATTEMPT_TOKEN=customfield_10043
+JIRA_CUSTOM_FIELD_ATTEMPT_STARTED=customfield_10044
+JIRA_CUSTOM_FIELD_HEARTBEAT=customfield_10045
+JIRA_CUSTOM_FIELD_RETRY_COUNT=customfield_10046
+JIRA_CUSTOM_FIELD_IGNORE_REASON=customfield_10047
+```
+
+Setup wizard note: running `openfleet --setup` and selecting Jira will
+open the Atlassian API token page (opt-in), list projects, and guide you
+through project/issue type selection interactively.
+
+See [JIRA_INTEGRATION.md](./JIRA_INTEGRATION.md) for full configuration and examples.
+
+---
+
+## Channels and control surfaces
+
+### Telegram (primary control channel)
+
+Core controls include:
+
+- `/help` (inline keyboard)
+- `/status`, `/tasks`, `/agents`, `/threads`, `/worktrees`
+- `/pause`, `/resume`, `/restart`, `/retry`
+- `/executor`, `/sdk`, `/kanban`, `/maxparallel`
+
+### Telegram Mini App (Control Center)
+
+A full interactive web UI that runs inside Telegram as a Mini App. Enable it with two env vars:
+
+```env
+TELEGRAM_MINIAPP_ENABLED=true
+TELEGRAM_UI_PORT=3080
+```
+
+Once enabled, the server auto-detects your LAN IP and sets the bot menu button.
+Access the Mini App from Telegram via:
+
+- **`/app`** command — sends an inline button to open the Control Center
+- **Menu button** — tap the bot's menu button (set automatically)
+- **Browser** — open `http://<your-lan-ip>:3080` directly
+
+The Mini App provides 7 tabs: Dashboard, Tasks, Agents, Infra, Control, Logs, and Settings — all with real-time WebSocket updates, haptic feedback, and native Telegram theming.
+
+**For public/remote access**, set up a tunnel (ngrok, Cloudflare Tunnel) and configure:
+
+```env
+TELEGRAM_UI_BASE_URL=https://your-tunnel-domain.example.com
+```
+
+**For local browser testing** (without Telegram auth):
+
+```env
+TELEGRAM_UI_ALLOW_UNSAFE=true
+```
+
+### WhatsApp (optional)
+
+Enable in env and authenticate:
+
+```bash
+openfleet --whatsapp-auth
+# or
+openfleet --whatsapp-auth --pairing-code
+```
+
+Telegram status commands include:
+
+- `/whatsapp`
+- `/container`
+
+---
+
+## Container isolation (optional)
+
+`container-runner` can isolate agent executions with:
+
+- Docker
+- Podman
+- Apple Container (`container`) on macOS
+
+Key env vars:
+
+- `CONTAINER_ENABLED=1`
+- `CONTAINER_RUNTIME=auto|docker|podman|container`
+- `CONTAINER_IMAGE=node:22-slim`
+- `MAX_CONCURRENT_CONTAINERS=3`
+
+---
+
+## Configuration model
+
+Load order (highest priority first):
+
+1. CLI flags
+2. environment variables
+3. `.env`
+4. `openfleet.config.json`
+5. built-in defaults
+
+### Files
+
+- `.env` — runtime/environment settings
+- `openfleet.config.json` — structured config (executors, failover, repos, profiles)
+- `.openfleet/agents/*.md` — prompt templates scaffolded by setup
+
+### SDK transport defaults
+
+`openfleet` supports explicit transport selectors per SDK shell:
+
+- `CODEX_TRANSPORT=sdk|auto|cli`
+- `COPILOT_TRANSPORT=sdk|auto|cli|url`
+- `CLAUDE_TRANSPORT=sdk|auto|cli`
+
+Setup now defaults all three to `sdk` for predictable persistent-session behavior.
+`auto` remains available when you intentionally want endpoint/CLI auto-detection.
+
+### Recommended profile split
+
+- Local development profile:
+  - `DEVMODE=true`
+  - `DEVMODE_MONITOR_MONITOR_ENABLED=true`
+  - `*_TRANSPORT=sdk`
+- End-user stability profile:
+  - `DEVMODE=false`
+  - `DEVMODE_MONITOR_MONITOR_ENABLED=false`
+  - `*_TRANSPORT=sdk`
+
+---
+
+## Recommended configuration path
+
+If you want a strong baseline with minimal decisions:
+
+1. Run `openfleet --setup`
+2. Pick **Recommended** mode
+3. Choose executor preset that matches your token budget and speed goals
+4. Configure AI provider credentials
+5. Configure Telegram
+6. Keep defaults for hooks/VK/orchestrator unless you already have a custom flow
+
+This gives you a standardized `.env` with full inline documentation and sane defaults.
+
+---
+
+## Advanced configuration path
+
+Use **Advanced** mode when you need:
+
+- custom multi-repo topology
+- custom failover/distribution behavior
+- manual orchestrator path/args
+- custom hook policy and event overrides
+- explicit VK URL/port and wiring behavior
+- explicit optional channel/runtime tuning
+
+---
+
+## Key config examples
+
+### Executor config (`openfleet.config.json`)
+
+```json
+{
+  "$schema": "./openfleet.schema.json",
+  "projectName": "my-project",
+  "executors": [
+    {
+      "name": "copilot-claude",
+      "executor": "COPILOT",
+      "variant": "CLAUDE_OPUS_4_6",
+      "weight": 50,
+      "role": "primary",
+      "enabled": true
+    },
+    {
+      "name": "codex-default",
+      "executor": "CODEX",
+      "variant": "DEFAULT",
+      "weight": 50,
+      "role": "backup",
+      "enabled": true
+    }
+  ],
+  "failover": {
+    "strategy": "next-in-line",
+    "maxRetries": 3,
+    "cooldownMinutes": 5,
+    "disableOnConsecutiveFailures": 3
+  },
+  "distribution": "weighted"
+}
+```
+
+### Env shorthand for executors
+
+```env
+EXECUTORS=COPILOT:CLAUDE_OPUS_4_6:50,CODEX:DEFAULT:50
+```
+
+### Minimal local env
+
+```env
+PROJECT_NAME=my-project
+GITHUB_REPO=myorg/myrepo
+KANBAN_BACKEND=internal
+KANBAN_SYNC_POLICY=internal-primary
+EXECUTOR_MODE=internal
+INTERNAL_EXECUTOR_REPLENISH_ENABLED=false
+PROJECT_REQUIREMENTS_PROFILE=feature
+VK_BASE_URL=http://127.0.0.1:54089
+VK_RECOVERY_PORT=54089
+MAX_PARALLEL=6
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=
+```
+
+For full variable documentation see `.env.example`.
+
+---
+
+## Useful commands
+
+```bash
+openfleet --help
+openfleet --setup
+openfleet --doctor
+openfleet --update
+openfleet --no-update-check
+openfleet --no-auto-update
+openfleet --no-telegram-bot
+openfleet --telegram-commands
+openfleet --no-vk-spawn
+openfleet --vk-ensure-interval 60000
+openfleet --script ./my-orchestrator.sh
+openfleet --args "-MaxParallel 6"
+```
+
+`--doctor` validates effective config (.env + config JSON + process env overrides), reports actionable fixes, and exits non-zero when blocking issues are found.
+
+---
+
+## Validation and tests
+
+From `scripts/openfleet`:
+
+```bash
+npm run syntax:check
+npm run test
+```
+
+Focused tests (example):
+
+```bash
+npx vitest run tests/whatsapp-channel.test.mjs tests/container-runner.test.mjs tests/telegram-buttons.test.mjs
+```
+
+---
+
+## Notes on generated `.env`
+
+The setup wizard now standardizes `.env` generation by applying your selected values onto `.env.example`.
+
+Benefits:
+
+- all options stay documented in your generated file
+- chosen values are explicitly activated/uncommented
+- unchosen options remain visible as commented documentation
+- easier upgrades over time as new options are added
+
+---
+
+## Troubleshooting quick checks
+
+- `openfleet --help` for supported flags
+- `openfleet --setup` to re-run configuration safely
+- verify `.env` + `openfleet.config.json` are in your config directory
+- verify `gh auth status` for PR operations
+- verify Telegram token/chat id with `openfleet-chat-id`
+
+---
+
+## License
+
+Apache 2.0