TaskHub V2

English | 中文

TaskHub V2 is a LangGraph-native AI software delivery control plane. The graph, not an application-owned SQL state machine, controls workflow state and recovery.

Current Scope

• One durable workflow thread per development run.
• Intake, planning, implementation, review, risk, and supervisor subgraphs.
• Automatic planning-to-implementation and supervision-to-publication transitions, with Command(resume=...) reserved for genuine recovery decisions.
• Memory checkpointer for development and PostgreSQL checkpointer for deployment.
• Plus/Pro device-auth accounts and GPT/DeepSeek/MiniMax API adapters.
• Ordered fallback with persisted cooldown, quota visibility, and preferred-provider recovery.
• Registered Git authorities, isolated per-run worktrees, real code changes, tests, patches, and commits.
• One-step project creation provisions a bare authority repository, clones a controller checkout, creates the initial commit, and registers the project.
• Automatic supervised publication, stale-base rebase, publication tests, fast-forward authority merge, and recoverable conflict reporting.
• Automatic supervisor-to-worker revision loops with bounded retries, durable revision commits, and an owner override at the configured limit.
• Authenticated execution nodes with capability-aware scheduling, per-node slots, sticky run assignment, failover, and visible node health.
• HTTP API, checkpoint history, SSE updates, and a small workflow timeline UI.

Provider secrets are loaded from /home/gryps/.config/taskhub-v2/providers.env in deployment. This file must remain mode 600 and is never returned by the API. ChatGPT account sessions remain in their Codex-managed CODEX_HOME directories. Use scripts/codex_account_login.sh plus|pro; device authorization opens at https://auth.openai.com/codex/device. OpenAI account and API traffic is forced through the configured proxy. DeepSeek and MiniMax are forced direct.

Test and build execution can be distributed with TASKHUB_TEST_RUNNER=scheduled. The controller sends a credential-filtered workspace archive to the selected node; model credentials and the Git authority remain on the controller.

Acceptance Prerequisites

Database acceptance is a node capability, not a project-owned credential. Install it on a designated Ubuntu acceptance node with scripts/install_test_database_node.sh. The node keeps the administrator DSN private, creates an isolated database for each execution, injects the configured environment names, and force-drops the database after success or failure. Projects that require it declare acceptance_capabilities: ["test_database"].

A managed project can register one dedicated deployed test environment from 系统配置 / 预生产环境 or through PUT /api/projects/{project_id}/test-environment. The form is available after a project is created or attached, persists the configuration in the project registry, and can disable it without editing configuration files. TaskHub stores its non-secret target URL, edge host, origin host, and expected environment. Acceptance commands receive these values as TASKHUB_TEST_TARGET_URL, TASKHUB_TEST_EDGE_HOST, TASKHUB_TEST_ORIGIN_HOST, TASKHUB_TEST_EXPECTED_ENVIRONMENT, and TASKHUB_TEST_ENVIRONMENT_PROFILE. SSH credentials and database administrator credentials remain node-private and are never project configuration.

When a project has a dedicated preproduction environment, its browser contract must use target: preproduction and define preproduction.prepare_command. The managed-project coding worker owns that command; the operator does not write it. TaskHub runs the command on an acceptance node with the target hosts and candidate commit injected, then requires the target health response to prove the exact Git commit, environment name, and database revision before dispatching Windows browser acceptance. A local preview result cannot satisfy a configured preproduction gate. Missing contract automation is automatically returned to the coding worker while a revision remains available.

Windows browser nodes configure TASKHUB_BROWSER_PROFILE_DIR, TASKHUB_BROWSER_AUTH_TARGET, and TASKHUB_BROWSER_AUTH_READY_FILE during admission. Run deploy/windows/authorize-browser-profile.ps1 once in the interactive desktop account. Browser jobs are rejected by preflight until the dedicated profile and authorization marker are present. Both states are visible under 系统配置 / 验收前置配置 before a project run starts.

Create A Project

The primary UI action is Create project. Enter a display name, select the project type, confirm the generated project ID and base branch, then submit. In the deployed topology TaskHub creates the bare authority repository on 192.168.31.3, creates its managed checkout on the controller, and adds it to the project selector. Attaching an existing controller checkout remains available as an advanced operation.

Managed projects record an authority_remote. Publication fetches that remote, rebases and retests when necessary, then pushes with a lease after supervision succeeds. A rejected push is a visible recoverable block and is never reported as successful.

Governed Self Deployment

Self deployment is disabled by default and can be bound to exactly one registered project with TASKHUB_SELF_DEPLOY_PROJECT_ID. After that project's run completes authority publication, the run view exposes Deploy and restart. Deployment runs in an independent user systemd unit so the control-plane restart cannot terminate it.

The executor verifies that the requested commit is the current authority branch, requires non-empty project test commands, tests an archived release candidate, keeps .env and .venv, restarts the configured service, and checks the health endpoint. An unhealthy release restores the prior application files and restarts the service. Deployment state is persisted outside the application directory.

Run Locally

cp .env.example .env
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
make run

Open http://localhost:8200.

Run The Seed Controller With Docker

The alpha seed deployment packages the current Web/API controller with a durable, internal PostgreSQL service. On Windows Docker Desktop run:

.\deploy\seed\start-seed.ps1

See docs/deployment/seed-node.md for scope, credentials, persistence, and acceptance checks. The alpha Web console can create role-selected containers on the Seed Docker host. SSH-based creation on additional physical hosts has been retired; docs/requirements/seed-ssh-multihost.md is retained only as a historical record.

For PostgreSQL persistence:

docker compose up -d postgres
sed -i.bak 's/TASKHUB_CHECKPOINTER=memory/TASKHUB_CHECKPOINTER=postgres/' .env
make run

Architecture Rules

• TaskHub maintainers never implement or repair managed-project code directly. Managed-project changes must come from a recorded TaskHub coding run; operators may repair only the platform, deployment, node environment, or configuration.
• Workflow transitions belong in src/taskhub_v2/workflows/ only.
• API handlers call application services and never mutate workflow state directly.
• Providers and workers implement protocols; graphs do not contain vendor or host logic.
• Project-specific commands and paths do not belong in platform core.
• Operators provide infrastructure and credentials only. TaskHub executes deployment, migration, acceptance, evidence collection, and cleanup without maintainer assistance.
• Python modules must remain below 400 lines; CI enforces this limit.
• Side effects must be idempotent because interrupted nodes restart from their beginning.

Verification

make test
make lint