ahub 3.0.0__py3-none-any.whl

ahub/__init__.py

@@ -0,0 +1,3 @@
+"""agent-hub v2: the service through which the orchestrator and humans hand work to worker models."""
+
+__version__ = "3.0.0"

ahub/__main__.py

@@ -0,0 +1,3 @@
+from ahub.cli import main
+
+raise SystemExit(main())

ahub/accept.py

@@ -0,0 +1,257 @@
+"""Decisions on results (V15–V18, architecture §6.7–§6.8): accept/merge, rework, reject, orchestrator edit,
+path extension, budget top-up, model change, resume with a new brief.
+
+Merge: task → "accepting" (lease held by whoever accepts; a second "accept" is refused) → gates at the copy's
+current HEAD (orchestrator edit — if HEAD ≠ worker result commit: legitimate, with an event) → in the project root
+`git merge --no-ff` into the work branch → acceptance under the test resource → red — roll the merge back →
+push per config → "accepted", task_cleanup hook, copy and branch removed, archived.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ahub import archive, events, gates, prepare, registry, tasks, transitions, workspace
+from ahub import log as hublog
+from ahub.config import ProjectConfig
+from ahub.engine import owner_token
+from ahub.i18n import t as _t
+from ahub.model import CHANGES_FILES, Ev, Kind, State
+from ahub.store import Store, Task
+
+_log = hublog.get("accept")
+
+
+class DecisionError(RuntimeError):
+    """Action impossible (one line for the orchestrator)."""
+
+
+def _get(store: Store, task_id: int) -> Task:
+    t = store.get_task(task_id)
+    if t is None:
+        raise DecisionError(_t("trans.no_task", id=task_id))
+    return t
+
+
+def _root_ready(project: ProjectConfig) -> None:
+    cur = workspace.git(project.root, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip()
+    if cur != project.work_branch:
+        raise DecisionError(_t("accept.root_branch", cur=cur, branch=project.work_branch))
+    dirty = [ln for ln in workspace.git(project.root, "status", "--porcelain", "--untracked-files=no").stdout
+             .splitlines() if ln.strip()]
+    if dirty:
+        raise DecisionError(_t("accept.root_dirty", files=", ".join(x[3:] for x in dirty[:5])))
+
+
+def accept(store: Store, project: ProjectConfig, task_id: int, *, by: str = "orchestrator") -> str:
+    t = _get(store, task_id)
+    if t.kind not in CHANGES_FILES:
+        if t.state not in (State.DONE, State.NEEDS_DECISION):
+            raise DecisionError(_t("accept.can_accept", label=t.label, state=t.state.value))
+        transitions.move(store, t.id, State.ACCEPTED, reason=_t("accept.accepted"), by=by)
+        events.ack_task(store, t.id)
+        archive.write_task(store, project, t.id)
+        workspace.remove(project, t.id, delete_branch=True)
+        return _t("accept.accepted_msg", label=t.label)
+    if t.state not in (State.DONE, State.NEEDS_DECISION, State.ACCEPTING):
+        raise DecisionError(_t("accept.can_accept", label=t.label, state=t.state.value))
+    if not t.worktree or not Path(t.worktree).is_dir():
+        raise DecisionError(_t("accept.no_worktree", label=t.label, wt=t.worktree or "—"))
+    _root_ready(project)
+    owner = owner_token()
+    if t.state is not State.ACCEPTING:
+        transitions.move(store, t.id, State.ACCEPTING, reason=_t("accept.accepting"), by=by,
+                         expect_from={State.DONE, State.NEEDS_DECISION})
+    if not transitions.acquire(store, t.id, owner, pid=None):
+        raise DecisionError(_t("accept.busy", label=t.label))
+    try:
+        return _merge(store, project, _get(store, t.id), owner, by)
+    except DecisionError as e:
+        _back(store, t.id, owner, str(e))
+        raise
+    except Exception as e:
+        _log.exception("accept T%d failed", t.id, extra={"task": t.id})
+        _back(store, t.id, owner, _t("accept.fail", err=f"{type(e).__name__}: {e}"))
+        raise DecisionError(_t("accept.fail", err=e)) from e
+    finally:
+        transitions.release(store, t.id, owner)
+
+
+def _back(store: Store, task_id: int, owner: str, reason: str) -> None:
+    t = store.get_task(task_id)
+    if t is not None and t.state is State.ACCEPTING:
+        transitions.move(store, task_id, State.NEEDS_DECISION, reason=reason[:500], by="accept", owner=owner)
+        events.ack_task(store, task_id)  # the orchestrator saw the refusal in the command output
+
+
+def _merge(store: Store, project: ProjectConfig, t: Task, owner: str, by: str) -> str:
+    res = archive.read_json(Path(t.worktree) / workspace.AHUB_DIR / "result.json")
+    head = workspace.head(t.worktree)
+    orch_edit = not res.get("commit") or not head.startswith(str(res.get("commit"))[:7])
+    if orch_edit and not t.limits.get("orch_edit"):
+        store.add_event(Ev.ORCH_EDIT, task_id=t.id, project=t.project,
+                        payload={"head": head[:12], "worker_commit": str(res.get("commit", ""))[:12], "by": by})
+    g = gates.check(project, t, run_tests=False, orch_edit=orch_edit)
+    problems = g.fatal + [p for p in g.repairable if not (orch_edit and p.startswith("result.json"))]
+    if problems:
+        raise DecisionError(_t("accept.gates_head", problems="; ".join(problems)))
+    title = t.title.replace('"', "'")[:100]
+    r = workspace.git(project.root, "merge", "--no-ff", "-m", f"merge {t.label}: {title}", t.branch, check=False)
+    if r.returncode != 0:
+        conflicts = workspace.git(project.root, "diff", "--name-only", "--diff-filter=U", check=False).stdout.split()
+        workspace.git(project.root, "merge", "--abort", check=False)
+        raise DecisionError(_t("accept.conflict", info=", ".join(conflicts[:10]) or (r.stderr or r.stdout)[-300:]))
+    merged = workspace.git(project.root, "rev-parse", "HEAD").stdout.strip()
+    nodes = list(t.limits.get("accept") or [])
+    if t.kind is Kind.CODE and nodes:
+        ok, tail, cmd = gates.run_acceptance(project, project.root, nodes, task_label=t.label)
+        if not ok:
+            head_now = workspace.git(project.root, "rev-parse", "HEAD").stdout.strip()
+            if head_now != merged:  # someone committed into the work branch meanwhile — leave foreign commits alone
+                raise DecisionError(_t("accept.root_moved", now=head_now[:10], merged=merged[:10]))
+            workspace.git(project.root, "reset", "--keep", "HEAD~1", check=False)  # --keep leaves foreign dirt alone
+            raise DecisionError(_t("accept.red_rolled_back", cmd=cmd, tail=tail[-600:]))
+    note = ""
+    if project.push.strip():
+        parts = project.push.split()
+        pr = workspace.git(project.root, "push", *parts, check=False, timeout=300)
+        if pr.returncode != 0:
+            note = _t("accept.push_fail", err=(pr.stderr or pr.stdout).strip()[-200:])
+            _log.warning("push T%d: %s", t.id, note, extra={"task": t.id})
+    transitions.move(store, t.id, State.ACCEPTED, reason=_t("accept.merged_reason", branch=project.work_branch,
+                                                             note=note), by=by, owner=owner,
+                     fields={"accepted_sha": merged})
+    events.ack_task(store, t.id)
+    try:
+        prepare.run_hook(project, "task_cleanup", t, t.worktree)
+    except prepare.PrepareError as e:
+        _log.warning("hook task_cleanup T%d: %s", t.id, e, extra={"task": t.id})
+    archive.write_task(store, project, t.id)
+    workspace.remove(project, t.id, delete_branch=True)
+    return _t("accept.merged_msg", label=t.label, branch=project.work_branch, sha=merged[:10], note=note)
+
+
+def reject(store: Store, project: ProjectConfig, task_id: int, *, reason: str = "", by: str = "orchestrator",
+           keep: bool = False) -> str:
+    t = _get(store, task_id)
+    try:
+        transitions.move(store, t.id, State.REJECTED, reason=reason or _t("accept.rejected_default"), by=by)
+    except (transitions.TransitionError, transitions.ConflictError) as e:
+        raise DecisionError(f"{e}{_t('accept.active_first')}") from e
+    events.ack_task(store, t.id)
+    archive.write_task(store, project, t.id)
+    if not keep:
+        workspace.remove(project, t.id, delete_branch=True)
+    return _t("accept.rejected_msg", label=t.label)
+
+
+def rework(store: Store, task_id: int, notes: str, *, by: str = "orchestrator") -> str:
+    """Send back for rework with notes: same executor session, new round."""
+    t = _get(store, task_id)
+    if t.state not in (State.DONE, State.NEEDS_DECISION, State.ERROR, State.STOPPED):
+        raise DecisionError(_t("accept.rework_state", label=t.label, state=t.state.value))
+    if not notes.strip():
+        raise DecisionError(_t("accept.need_notes"))
+    lim = dict(t.limits)
+    lim["rework_notes"] = notes.strip()
+    store.update_task(t.id, limits=lim)
+    transitions.move(store, t.id, State.QUEUED, reason=_t("accept.rework"), by=by, fields={"round": t.round + 1},
+                     payload={"notes": notes[:500]})
+    events.ack_task(store, t.id)
+    return _t("accept.rework_msg", label=t.label, round=t.round + 1)
+
+
+def continue_task(store: Store, task_id: int, *, by: str = "orchestrator") -> str:
+    t = _get(store, task_id)
+    if t.state not in (State.STOPPED, State.ERROR, State.NEEDS_DECISION):
+        raise DecisionError(_t("accept.continue_state", label=t.label, state=t.state.value))
+    transitions.move(store, t.id, State.QUEUED, reason=_t("accept.continue"), by=by)
+    events.ack_task(store, t.id)
+    return _t("accept.continued_msg", label=t.label)
+
+
+def edit(store: Store, project: ProjectConfig, task_id: int, *, spec: str | None = None,
+         title: str | None = None, by: str = "orchestrator") -> str:
+    """New brief: on resume — a fresh executor session (different fingerprint)."""
+    t = _get(store, task_id)
+    if t.state in (State.ACCEPTED, State.REJECTED) or t.state in transitions.ACTIVE:
+        raise DecisionError(_t("accept.edit_state", label=t.label))
+    new = tasks.TaskSpec(project=t.project, kind=t.kind, title=title if title is not None else t.title,
+                         spec=spec if spec is not None else t.spec, result_format=t.result_format,
+                         paths=list(t.limits.get("paths") or []), accept=list(t.limits.get("accept") or []),
+                         review_input=str(t.limits.get("input") or ""))
+    h = tasks.spec_hash(new)
+    if h == t.spec_hash:
+        return _t("accept.edit_same", label=t.label)
+    lim = dict(t.limits)
+    lim["fresh_session"] = True
+    store.update_task(t.id, title=new.title, spec=new.spec, spec_hash=h, limits=lim)
+    store.add_event(Ev.STATE, task_id=t.id, project=t.project, payload={"edit": _t("accept.edit_text"), "by": by})
+    return _t("accept.edit_msg", label=t.label)
+
+
+def extend_paths(store: Store, project: ProjectConfig, task_id: int, paths: list[str], *,
+                 by: str = "orchestrator") -> str:
+    t = _get(store, task_id)
+    bad = [p for p in paths if tasks._path_escapes(p) or not tasks._glob_allowed(p, project.allowed_paths)]
+    if bad:
+        raise DecisionError(_t("accept.paths_outside", items=", ".join(bad)))
+    cur = list(t.limits.get("paths") or [])
+    added = [p for p in paths if p not in cur]
+    if not added:
+        return _t("accept.paths_same", label=t.label)
+    lim = dict(t.limits)
+    lim["paths"] = cur + added
+    store.update_task(t.id, limits=lim)
+    store.add_event(Ev.PATHS_EXTENDED, task_id=t.id, project=t.project, payload={"added": added, "by": by})
+    return _t("accept.paths_added", label=t.label, items=", ".join(added))
+
+
+def _stopped_by_budget(store: Store, task_id: int) -> bool:
+    """Task parked on budget: after a hard budget stop (budget_hard) it never left "needs decision"."""
+    stopped = False
+    for e in store.events(task_id=task_id):
+        if e.kind == Ev.BUDGET_HARD.value:
+            stopped = True
+        elif e.kind == Ev.STATE.value and (e.payload or {}).get("to") != State.NEEDS_DECISION.value:
+            stopped = False
+    return stopped
+
+
+def extend_budget(store: Store, task_id: int, *, add: float | None = None, set_to: float | None = None,
+                  add_usd: float | None = None, by: str = "orchestrator") -> str:
+    """Top up the budget in one move: raised + resumed (if the task was parked on budget).
+
+    add/set_to — Go counter (subscription); add_usd — real money (default 0 = no spending).
+    """
+    t = _get(store, task_id)
+    new = set_to if set_to is not None else t.budget_go + (add or 0.0)
+    new_usd = t.budget_usd + (add_usd or 0.0)
+    if new <= t.budget_go and set_to is None and new_usd <= t.budget_usd:
+        raise DecisionError(_t("accept.budget_need"))
+    store.update_task(t.id, budget_go=float(new), budget_usd=float(new_usd))
+    store.add_event(Ev.BUDGET_EXTENDED, task_id=t.id, project=t.project,
+                    payload={"from": t.budget_go, "to": new, "usd_from": t.budget_usd, "usd_to": new_usd, "by": by})
+    msg = _t("accept.budget_msg", label=t.label, old=f"{t.budget_go:g}", new=f"{new:g}") + (
+        _t("accept.budget_usd", old=f"{t.budget_usd:g}", new=f"{new_usd:g}")
+        if new_usd != t.budget_usd else "")
+    if t.state is State.NEEDS_DECISION and _stopped_by_budget(store, t.id):
+        transitions.move(store, t.id, State.QUEUED, reason=_t("accept.budget_long"), by=by)
+        events.ack_task(store, t.id)
+        msg += _t("accept.budget_resumed")
+    return msg
+
+
+def change_model(store: Store, project: ProjectConfig, task_id: int, alias: str, *, by: str = "orchestrator") -> str:
+    t = _get(store, task_id)
+    if t.state in transitions.ACTIVE:
+        raise DecisionError(_t("accept.model_active", label=t.label))
+    try:
+        registry.check(store, alias, project)
+    except registry.RegistryError as e:
+        raise DecisionError(str(e)) from e
+    lim = dict(t.limits)
+    lim["fresh_session"] = True  # never resume another model's session
+    store.update_task(t.id, executor=alias, limits=lim)
+    store.add_event(Ev.MODEL_CHANGED, task_id=t.id, project=t.project, payload={"from": t.executor, "to": alias, "by": by})
+    return _t("accept.model_msg", label=t.label, old=t.executor, new=alias)

ahub/archive.py

@@ -0,0 +1,129 @@
+"""Task archive inside the project (architecture §12): `<project>/.agent-hub/` — local, not in project git.
+
+tasks.md — shared list; tasks/T<id>/ — brief, worker result, report, diff (for code), cost, outcome.
+The hub only writes; a human cleans up. Archive errors never break work — just a log line.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+from ahub import log as hublog
+from ahub import workspace
+from ahub.config import ProjectConfig
+from ahub.i18n import Words
+from ahub.i18n import t as _t
+from ahub.model import CHANGES_FILES
+from ahub.store import Store, Task
+from ahub.time import fmt_local
+
+DIR = ".agent-hub"
+STATE_WORDS: Words = Words("archive.state_", ("draft", "queued", "preparing", "working", "checking",
+                                             "reviewing", "fixing", "done", "needs_decision", "error",
+                                             "stopped", "accepting", "accepted", "rejected"))
+_log = hublog.get("archive")
+
+
+def root(project: ProjectConfig) -> Path:
+    return Path(project.root) / DIR
+
+
+def _exclude(project: ProjectConfig) -> None:
+    try:
+        r = workspace.git(project.root, "rev-parse", "--git-path", "info/exclude", check=False)
+        if r.returncode != 0:
+            return
+        excl = Path(r.stdout.strip())
+        if not excl.is_absolute():
+            excl = Path(project.root) / excl
+        excl.parent.mkdir(parents=True, exist_ok=True)
+        lines = excl.read_text(encoding="utf-8").splitlines() if excl.exists() else []
+        if f"{DIR}/" not in lines:
+            with excl.open("a", encoding="utf-8") as f:
+                f.write(f"\n{DIR}/\n")
+    except (OSError, workspace.WorkspaceError):
+        pass
+
+
+def task_cost(store: Store, task_id: int) -> tuple[float, float]:
+    go = usd = 0.0
+    for s in store.list_sessions(task_id):
+        go += s.cost_go or 0.0
+        usd += s.cost_usd or 0.0
+    return go, usd
+
+
+def _task_md(store: Store, t: Task) -> str:
+    go, usd = task_cost(store, t.id)
+    sessions = store.list_sessions(t.id)
+    lines = [f"# {t.label} — {t.title}", "",
+             _t("archive.type", kind=t.kind.value, state=STATE_WORDS.get(t.state.value, t.state.value))
+             + (f" — {t.state_reason}" if t.state_reason else ""),
+             _t("archive.model", executor=t.executor,
+               review=', '.join(t.review.get('models', [])) or _t("archive.no_review"))
+             + (f" × {t.review.get('rounds')}" if t.review else ""),
+             _t("archive.rounds", round=t.round, sessions=len(sessions)),
+             _t("archive.cost", go=f"{go:.3f}") + (_t("archive.cost_real", usd=f"{usd:.3f}") if usd else ""),
+             _t("archive.created", when=fmt_local(t.created_at), by=t.created_by or '—')
+             + (_t("archive.finished", when=fmt_local(t.finished_at)) if t.finished_at else ""),
+             ""]
+    if t.after:
+        lines.insert(-1, _t("archive.after", items=', '.join(f'T{a}' for a in t.after)))
+    if t.limits.get("paths"):
+        lines.insert(-1, _t("archive.paths", items=', '.join(t.limits['paths'])))
+    if t.limits.get("accept"):
+        lines.insert(-1, _t("archive.accept", items=', '.join(t.limits['accept'])))
+    if t.spec.strip():
+        lines += [_t("archive.spec"), "", t.spec.strip(), ""]
+    return "\n".join(lines)
+
+
+def write_task(store: Store, project: ProjectConfig, task_id: int) -> Path | None:
+    try:
+        t = store.get_task(task_id)
+        if t is None:
+            return None
+        base = root(project)
+        d = base / "tasks" / t.label
+        d.mkdir(parents=True, exist_ok=True)
+        _exclude(project)
+        (d / "task.md").write_text(_task_md(store, t), encoding="utf-8")
+        if t.worktree and Path(t.worktree).is_dir():
+            src = Path(t.worktree) / workspace.AHUB_DIR
+            for name in ("result.json", "report.md"):
+                if (src / name).is_file():
+                    shutil.copyfile(src / name, d / name)
+            for rv in src.glob("review_r*.json"):
+                shutil.copyfile(rv, d / rv.name)
+            if t.kind in CHANGES_FILES and t.base_sha:
+                r = workspace.git(t.worktree, "diff", f"{t.base_sha}..HEAD", check=False)
+                if r.returncode == 0:
+                    (d / "diff.patch").write_text(r.stdout, encoding="utf-8")
+        write_index(store, project)
+        return d
+    except Exception:
+        _log.exception("archive T%s not written", task_id, extra={"task": task_id})
+        return None
+
+
+def write_index(store: Store, project: ProjectConfig) -> None:
+    tasks = store.list_tasks(project=project.name, newest_first=True)
+    rows = [_t("archive.index_title"), "", _t("archive.index_head"), "|---|---|---|---|---|---|"]
+    for t in tasks:
+        go, usd = task_cost(store, t.id)
+        title = t.title.replace("|", "/")[:80]
+        rows.append(f"| [{t.label}](tasks/{t.label}/task.md) | {fmt_local(t.created_at)} | {t.kind.value} | {title} |"
+                    f" {STATE_WORDS.get(t.state.value, t.state.value)} | {go + usd:.3f} |")
+    base = root(project)
+    base.mkdir(parents=True, exist_ok=True)
+    (base / "tasks.md").write_text("\n".join(rows) + "\n", encoding="utf-8")
+
+
+def read_json(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}

ahub/claude/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: ahub
+description: Work with agent-hub (ahub CLI) — delegate scout, code, routine or review to cheap worker models (Spark etc.), wait without polling, read the result briefly, accept and merge. Use when a task is cheaper to delegate, or when an ahub event line arrives (DONE/DECISION/ERROR/OWNER/ANSWER/ALARM).
+---
+
+# agent-hub: how to work cheaply
+
+The hub runs tasks itself (project copy, worker, gates, review, retries on failures). Your job — file a task,
+wake on an event, read the result and decide. Don't poll the hub: it wakes you.
+
+## 1. Session start
+- Start a Monitor on `ahub watch` (description: "ahub: events for Claude"). Each line is work for you.
+  Monitor lives ≤ 30 min: restart on expiry (events are not lost — position is in the hub DB).
+- What's going on: `ahub status` (≤ 1.5 KB).
+
+## 2. File a task
+```
+ahub task new --kind scout   --title "goal" --spec "what to find, where to look, what goes in the report"
+ahub task new --kind code    --title "goal" --spec-file spec.md --paths "core/**,tests/**" \
+              --accept "tests/test_x.py::test_y" [--level 0..4] [--after T3] [--budget 1.5]
+ahub task new --kind routine --title "tidy up docs/" --paths "docs/**"
+ahub task new --kind review  --title "check the branch" --input "main..feature"
+```
+- Review level: 0 — none; 1 — docs/routine; 2 — regular code (default for code); 3–4 — near money.
+- Spec is self-contained: what to do, which files, how to verify, what not to touch. External facts (API, prices)
+  verify with a live call BEFORE filing. A task that fails validation — error comes in one line, no model is called.
+- Models: `ahub models` (role menu; project bans cannot be bypassed).
+
+## 3. Woke on an event
+- `DONE T12 …` → `ahub status T12` (result, report essence, checks, cost — ≤ 4 KB; confirms the event).
+  Full report — `ahub result T12 --full`, diff — `ahub diff T12`, raw logs — `ahub log T12` (only if needed).
+- Decide: `ahub accept T12` (scout — accept; code/routine — merge into the working branch, acceptance reruns,
+  on red — rollback) · `ahub rework T12 --notes "what to fix"` (same session, new round) · `ahub reject T12`.
+- Your own small fix on top of the result: commit in the task copy (`ahub status T12` shows the path), then
+  `ahub accept T12` — this is legal ("orchestrator edit"). Need more files — `ahub extend T12 --paths "…"`.
+- `DECISION T12 …` → read the reason (`ahub status T12`): rounds over, budget (`ahub budget T12 --add 1` —
+  the task resumes itself), files outside allowed paths, failure. Resume — `ahub continue T12`, change model —
+  `ahub model T12 mimo-flash`, new spec — `ahub task edit T12 --spec-file …`.
+- `ERROR T12 …` → reason is in the line; usually `ahub continue` after fixing the environment or `ahub reject`.
+
+Old events may start with Russian words ГОТОВО/РЕШЕНИЕ/ОШИБКА/ВЛАДЕЛЕЦ/ОТВЕТ/ТРЕВОГА instead of codes — same events.
+
+## 4. Owner
+- `OWNER «…»` → `ahub inbox` (read), reply — `ahub say "short, in the owner's language"`.
+- Need approval (merge, extend, spend) — `ahub ask "merge T12?" --options "yes,no"`; the answer comes as
+  `ANSWER #N … → yes`. Merge code only with owner approval if they asked for it.
+- `ALARM …` → the observer found a problem with the hub itself: `ahub alarms`, `ahub service status`,
+  `ahub observer reports`.
+
+## 5. Economy
+- Don't read L3 (full report, diff, logs) without need — L2 is usually enough to decide.
+- Recon is cheaper than your code reading: give search and survey to the worker, read the essence.
+- Parallel tasks — in one batch; dependent — `--after T3` (starts after T3 is accepted, for code with it).

ahub/cli.py

@@ -0,0 +1,77 @@
+"""ahub entry point: subcommands are ahub/commands/*.py modules with register(subparsers).
+
+Shared `--json` flag — machine output; default compact text (orchestrator token savings).
+Config errors and expected refusals — one stderr line and exit 2, no traceback.
+
+Imports live inside functions: main() refuses on Windows before command imports
+(some modules pull fcntl, which is missing there).
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def _discover(subparsers) -> list[str]:
+    import importlib
+    import pkgutil
+
+    import ahub.commands as _cmds
+
+    found = []
+    for mod in sorted(pkgutil.iter_modules(_cmds.__path__), key=lambda m: m.name):
+        if mod.name.startswith("_"):
+            continue
+        module = importlib.import_module(f"ahub.commands.{mod.name}")
+        if hasattr(module, "register"):
+            module.register(subparsers)
+            found.append(mod.name)
+    return found
+
+
+def build_parser():
+    import argparse
+
+    from ahub.i18n import t
+
+    ap = argparse.ArgumentParser(prog="ahub", description=t("cli.desc"))
+    ap.add_argument("--json", action="store_true", help=t("cli.help_json"))
+    ap.add_argument("--lang", choices=("en", "ru"), default=None, help=t("cli.help_lang"))
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    _discover(sub)
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    if sys.platform == "win32":
+        from ahub.i18n import t as _t
+
+        print(_t("cli.err_win"), file=sys.stderr)
+        return 2
+    from ahub import log
+    from ahub.cliutil import CliError
+    from ahub.config import ConfigError
+    from ahub.i18n import set_lang, t
+
+    ap = build_parser()
+    args = ap.parse_args(argv)
+    if getattr(args, "lang", None):
+        set_lang(args.lang)
+    func = getattr(args, "func", None)
+    if func is None:
+        ap.print_help()
+        return 2
+    try:
+        return int(func(args) or 0)
+    except (ConfigError, CliError) as e:
+        print(t("cli.error", msg=e), file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+    except Exception:
+        log.get("cli").exception("command %s failed", args.cmd)
+        raise
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ahub/cliutil.py

@@ -0,0 +1,56 @@
+"""Shared by subcommands: text/JSON output, project pick."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from ahub import config
+
+
+class CliError(RuntimeError):
+    """Expected command refusal: printed on one line, exit 2."""
+
+
+def emit(args, data: Any, text: str) -> None:
+    """--json → data as JSON, else text."""
+    if getattr(args, "json", False):
+        json.dump(data, sys.stdout, ensure_ascii=False, separators=(",", ":"), default=str)
+        sys.stdout.write("\n")
+    else:
+        sys.stdout.write(text if text.endswith("\n") or not text else text + "\n")
+
+
+def add_project_arg(parser) -> None:
+    from ahub.i18n import t
+
+    parser.add_argument("--project", "-P", default=None, help=t("cli.help_project"))
+
+
+def resolve_project(args, cwd: str | Path | None = None) -> config.ProjectConfig:
+    """Project by --project (hub config name or path) or by current dir."""
+    want = getattr(args, "project", None)
+    cwd = Path(cwd) if cwd is not None else Path.cwd()
+    if want:
+        p = Path(config.expand(want))
+        if p.exists():
+            return config.load_project(p)
+        projects, _errors = config.load_projects()
+        for cfg in projects:
+            if cfg.name == want:
+                return cfg
+        from ahub.i18n import t
+
+        raise CliError(t("err.no_project", want=want))
+    try:
+        return config.load_project(cwd)
+    except FileNotFoundError:
+        projects, _errors = config.load_projects()
+        cfg = config.project_for(cwd, projects)
+        if cfg is None:
+            from ahub.i18n import t
+
+            raise CliError(t("err.no_project_cwd", cwd=cwd, file=config.PROJECT_FILE))
+        return cfg

ahub/commands/__init__.py

@@ -0,0 +1 @@
+"""ahub subcommands: each module exposes register(subparsers)."""

ahub/commands/bot.py

@@ -0,0 +1,26 @@
+"""ahub bot run — TG bot v2 (link to Claude, task view, alarms, Claude launch)."""
+
+from __future__ import annotations
+
+import importlib.util
+
+from ahub.cliutil import CliError
+
+
+def cmd_run(args) -> int:
+    if importlib.util.find_spec("aiogram") is None:
+        from ahub.i18n import t
+
+        raise CliError(t("err.no_telegram"))
+    from ahub.tg.run import main
+
+    return main()
+
+
+def register(subparsers) -> None:
+    from ahub.i18n import t
+
+    p = subparsers.add_parser("bot", help=t("help.bot"))
+    sub = p.add_subparsers(dest="bot_cmd", required=True)
+    r = sub.add_parser("run", help=t("help.bot_run"))
+    r.set_defaults(func=cmd_run)