caokit 0.3.0.dev0__py3-none-any.whl

caokit/data/scaffold/company/prompts/first-run.md

@@ -0,0 +1,18 @@
+Execute TASK-0001 from `.company/tasks/TASK-0001-smoke-test.md`.
+
+Follow this exact sequence:
+
+1. Read `.company/COMPANY.md`, every file under `.company/contracts/`, and the TASK-0001 file.
+2. Confirm the only permitted writes are the paths listed in TASK-0001.
+3. Use CAO `assign` to launch the profile ROSTER.md lists for `engineer` with the Engineering deliverable from TASK-0001. Name the exact artifact path. State that source changes and mutating commands are forbidden.
+4. Record the returned engineer terminal ID in `.company/TEAM.md`.
+5. Use CAO `assign` to launch the profile ROSTER.md lists for `scout` with the Scout deliverable from TASK-0001. Name the exact artifact path. State that source changes and external side effects are forbidden.
+6. Record the returned scout terminal ID in `.company/TEAM.md`.
+7. Do not perform either worker's assignment yourself. Become idle after dispatch so callbacks can arrive.
+8. Wait until both workers have sent callbacks. Reuse and message an existing worker if clarification is needed; do not create duplicates.
+9. Verify both artifact files exist and are non-empty.
+10. Use CAO `handoff` to the profile ROSTER.md lists for `inspector`. Instruct it to read TASK-0001 and both worker artifacts, then write `.company/reviews/TASK-0001-cross-provider-review.md`.
+11. Read the review and write `.company/decisions/TASK-0001-general-synthesis.md`.
+12. Check each acceptance criterion as PASS, FAIL, or NOT VERIFIED with evidence.
+13. Do not edit application source, run deployment actions, merge, push, or access secrets.
+14. Finish by reporting only the task state, worker terminal IDs, artifact paths, failed/not-verified checks, and decisions required from the human.

caokit/data/scaffold/company/tasks/TASK-0001-smoke-test.md

@@ -0,0 +1,109 @@
+# TASK-0001: Role-based orchestration smoke test
+
+- **State:** APPROVED
+- **Owner:** `general`
+- **Workers:** `engineer`, `scout`
+- **Reviewer:** `inspector`
+
+## Objective
+
+Prove that the General can launch and coordinate one engineer and one scout, collect file-based artifacts from both, obtain an independent review, and write a synthesis.
+
+## Inputs
+
+- repository contents,
+- `.company/COMPANY.md`,
+- all `.company/contracts/*.md` files.
+
+## Allowed paths
+
+All agents may read the repository according to their profile. Writes are limited to:
+
+- `.company/TEAM.md`
+- `.company/BACKLOG.md`
+- `.company/artifacts/TASK-0001-engineering-assessment.md`
+- `.company/research/TASK-0001-agy-product-assessment.md`
+- `.company/reviews/TASK-0001-cross-provider-review.md`
+- `.company/decisions/TASK-0001-general-synthesis.md`
+
+## Forbidden paths and actions
+
+- no application-source modifications,
+- no dependency or lockfile changes,
+- no Git state changes,
+- no deployment, merge, push, or publishing,
+- no credentials, secrets, production systems, or external side effects,
+- no worker may spawn another worker.
+
+## Engineering deliverable (`engineer`)
+
+Write `.company/artifacts/TASK-0001-engineering-assessment.md` covering:
+
+- repository structure and primary components,
+- likely execution path or architecture,
+- test and validation setup,
+- five technical risks or improvement opportunities,
+- three candidate engineering tasks with estimated complexity,
+- explicit unknowns.
+
+Do not modify application source and do not run commands that mutate the project.
+
+## Scout deliverable
+
+Write `.company/research/TASK-0001-agy-product-assessment.md` covering:
+
+- apparent product purpose and target user,
+- observed user journey from repository evidence,
+- missing or ambiguous product capabilities,
+- three possible product directions,
+- questions requiring human validation,
+- sources and evidence for any web-derived statements.
+
+Do not modify application source or perform external side effects.
+
+## Review deliverable
+
+`inspector` writes `.company/reviews/TASK-0001-cross-provider-review.md` covering:
+
+- task-scope compliance,
+- overlap and disagreement between artifacts,
+- unsupported or weakly supported claims,
+- whether each acceptance check passes,
+- blockers before a source-changing prototype task.
+
+## General deliverable
+
+Write `.company/decisions/TASK-0001-general-synthesis.md` with:
+
+- provider routing proof,
+- worker terminal IDs,
+- completed artifact paths,
+- agreements and disagreements,
+- recommended next milestone,
+- proposed TASK-0002,
+- decisions required from the human.
+
+## Acceptance checks
+
+- [ ] The active CAO session shows the General.
+- [ ] The General launches the profile ROSTER.md lists for `engineer`.
+- [ ] The General launches the profile ROSTER.md lists for `scout`.
+- [ ] Both workers return callbacks to the General.
+- [ ] Both required worker artifacts exist and are non-empty.
+- [ ] No application-source file is modified.
+- [ ] `inspector` produces the review artifact.
+- [ ] The General produces the synthesis artifact.
+- [ ] The synthesis records unresolved uncertainty rather than inventing missing evidence.
+
+## Validation
+
+```bash
+git status --short
+find .company -type f -print
+```
+
+Application-source changes cause this task to fail.
+
+## Approval boundary
+
+The human must approve any source-changing follow-up task.

caokit/data/scaffold/company/tasks/TASK_TEMPLATE.md

@@ -0,0 +1,73 @@
+# <TASK-ID>: <Title>
+
+- **State:** PROPOSED
+- **Owner role:** <role, e.g. `engineer`; the General resolves it via ROSTER.md>
+- **Reviewer role:** <role `inspector`; its tool must differ from the owner's for source changes>
+- **Depends on:** <TASK-NNNN, TASK-NNNN, or `none`; the task is blocked until each is ACCEPTED>
+- **Created:** <YYYY-MM-DD>
+- **Approved by human:** <date and how, filled in only after approval>
+
+## Objective
+
+<One concrete, observable outcome.>
+
+## Inputs
+
+- <file, artifact, decision, or source>
+
+## Allowed paths
+
+- <file or directory the worker may modify; prefer files>
+
+## Forbidden paths and actions
+
+- <path or action>
+
+## Deliverables
+
+- `<exact artifact path>`
+- <source change, when authorized>
+
+## Acceptance checks (human must confirm)
+
+- [ ] <observable criterion>
+- [ ] <observable criterion>
+
+## Authorised validation commands
+
+The engineer and the reviewer may run exactly these commands, and nothing else: no deletes, no cleanup, no installs, no state-changing git commands. The engineer must run them before reporting `COMPLETED`; the reviewer re-runs them independently. Both paste the real output in a **Commands run** section. Prefer commands that leave no generated files behind (for Python: `python3 -B -m unittest ...`).
+
+```bash
+<command>
+git status --short
+```
+
+## Team plan
+
+Filled in by the captain, with an estimate for every agent including the captain. On the plan path the human approves this section before anything launches. Cost is a rough range of fresh tokens (input + output + cache writes, no cache reads) with a low/med/high label and a few words of basis. Mark the path taken: **Path:** FAST | PLAN
+
+| Sub-task | Depends on | Agent (profile/role) | Why this agent | Parallel with | Est. cost |
+|---|---|---|---|---|---|
+| <sub-task> | <ids or NONE> | <agent> | <reason> | <ids or NONE> | <tokens or low/med/high> |
+
+- **Total agents:** <n> (fast path: at most 2)
+- **Plan-path triggers hit:** <auth/secrets | data | dependency | external | ambiguity | >2 agents | NONE>
+- **Clarification rounds so far:** 0
+
+## Approval boundary
+
+The human must approve before:
+
+- <action>
+
+## Dependencies
+
+- <task or decision, or NONE>
+
+## Open questions
+
+- <anything the General could not determine from the repository, or NONE>
+
+## Callback format
+
+Use the standard callback in `.company/contracts/COMMUNICATION_CONTRACT.md`.

caokit/doctor.py

@@ -0,0 +1,287 @@
+"""`caokit doctor`: what is installed, authenticated and consistent."""
+
+import os
+import re
+import shutil
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .adapters import Runner, adapter_ids, default_runner, load_adapter
+from .config import Config, ConfigError, default_path, load_config
+from .roster import check_roster
+
+# PyPI/uv name of CAO (not the `cao` binary name).
+CAO_PKG = "cli-agent-orchestrator"
+
+# Looks up an executable on PATH; returns its path or None (like shutil.which).
+Which = Callable[[str], str | None]
+
+
+@dataclass
+class Check:
+    """One line of the doctor report."""
+
+    level: str  # "ok" | "warn" | "fail"
+    text: str
+
+
+@dataclass
+class Report:
+    """Ordered list of checks produced by :func:`run_doctor`."""
+
+    checks: list[Check] = field(default_factory=list)
+
+    def add(self, level: str, text: str) -> None:
+        """Append a check.
+
+        Args:
+            level: One of ``"ok"``, ``"warn"`` or ``"fail"``.
+            text: Human-readable description of the finding.
+        """
+        self.checks.append(Check(level, text))
+
+    @property
+    def failed(self) -> bool:
+        """Whether any check has level ``"fail"`` (drives the exit code)."""
+        return any(c.level == "fail" for c in self.checks)
+
+
+def _run(runner: Runner, argv: Sequence[str]) -> str | None:
+    """Run a command and return its combined output, or None if it did not succeed.
+
+    Args:
+        runner: Command runner (injected so tests need no real CLIs).
+        argv: Command and arguments.
+
+    Returns:
+        Stripped stdout+stderr on exit code 0; None on a non-zero exit or when
+        the command could not be run at all.
+    """
+    try:
+        r = runner(argv)
+    except Exception:  # noqa: BLE001 - missing binary, timeout, etc. all mean "unavailable"
+        return None
+    return ((r.stdout or "") + (r.stderr or "")).strip() if r.returncode == 0 else None
+
+
+def _cao_installs(runner: Runner, which: Which) -> list[str]:
+    """Find CAO installs other than the uv tool (pipx, or pip in a PATH python).
+
+    Args:
+        runner: Command runner.
+        which: PATH lookup function.
+
+    Returns:
+        Labels of the extra installs; empty when there are none.
+    """
+    extra: list[str] = []
+    if which("pipx"):
+        out = _run(runner, ["pipx", "list", "--short"])
+        if out and re.search(rf"(?m)^{CAO_PKG} ", out):
+            extra.append("pipx")
+    seen: set[str] = set()
+    for name in ("python3", "python3.9", "python3.10", "python3.11", "python3.12", "python3.13"):
+        p = which(name)
+        if not p:
+            continue
+        # Resolve symlinks so python3 and python3.12 are not probed twice.
+        real = os.path.realpath(p)
+        if real in seen:
+            continue
+        seen.add(real)
+        code = f"import importlib.metadata as m; print(m.version('{CAO_PKG}'))"
+        if _run(runner, [real, "-c", code]):
+            extra.append(f"pip in {real}")
+    return extra
+
+
+def _check_cao(rep: Report, expected: str, runner: Runner, which: Which) -> None:
+    """Add checks for the cao binary: presence, exact version, uv origin, single install.
+
+    Args:
+        rep: Report to append to.
+        expected: CAO version this kit is validated against.
+        runner: Command runner.
+        which: PATH lookup function.
+    """
+    if not which("cao"):
+        rep.add(
+            "fail",
+            f"cao not found on PATH (uv tool install 'cli-agent-orchestrator=={expected}')",
+        )
+        return
+    v = _run(runner, ["cao", "--version"]) or ""
+    m = re.search(r"(\d+\.\d+\.\d+)", v)
+    if not m:
+        rep.add("fail", "cannot read `cao --version`")
+    elif m.group(1) != expected:
+        # A different version is a failure, not a warning: the kit is only validated on one.
+        rep.add(
+            "fail",
+            f"cao {m.group(1)} found, expected {expected} "
+            "(change only with `uv tool install --force 'cli-agent-orchestrator==X'`)",
+        )
+    else:
+        rep.add("ok", f"cao {m.group(1)}")
+    if which("uv"):
+        out = _run(runner, ["uv", "tool", "list"]) or ""
+        if re.search(rf"(?m)^{CAO_PKG} ", out):
+            rep.add("ok", "cao installed as a uv tool")
+        else:
+            rep.add("warn", "cao is not a uv tool install")
+    extra = _cao_installs(runner, which)
+    if extra:
+        joined = ", ".join(extra)
+        rep.add("fail", f"additional cao installs found: {joined} (keep exactly one, the uv tool)")
+    else:
+        rep.add("ok", "single cao install")
+
+
+def _check_server(rep: Report, runner: Runner, which: Which) -> None:
+    """Add checks that cao-server answers and serves its web UI.
+
+    A reachable server that returns 404 for ``/`` is usually an old process started from a
+    previous CAO install, which a restart fixes. Not running is only a warning, since the
+    server starts on demand.
+
+    Args:
+        rep: Report to append to.
+        runner: Command runner.
+        which: PATH lookup function.
+    """
+    if not which("curl"):
+        return
+    base = "http://{}:{}".format(
+        os.environ.get("CAO_API_HOST", "127.0.0.1"), os.environ.get("CAO_API_PORT", "9889")
+    )
+    health = _run(runner, ["curl", "-s", "-m", "3", base + "/health"])
+    if not health:
+        rep.add("warn", "cao-server is not running (start it with `caokit server`)")
+        return
+    rep.add("ok", "cao-server is running")
+    code = _run(
+        runner, ["curl", "-s", "-m", "3", "-o", "/dev/null", "-w", "%{http_code}", base + "/"]
+    )
+    if code == "200":
+        rep.add("ok", "cao-server serves its web UI")
+    else:
+        rep.add(
+            "warn",
+            f"cao-server web UI answered {code or 'nothing'} at /: restart the server "
+            "(`caokit stop` your sessions, stop the old cao-server, run `caokit server`)",
+        )
+
+
+def _check_tools(rep: Report, used: set[str], runner: Runner, which: Which) -> None:
+    """Add checks for every adapter's CLI: binary, version and auth.
+
+    A missing or unauthenticated tool is a failure only if the roster uses it.
+
+    Args:
+        rep: Report to append to.
+        used: Tool IDs referenced by the configured roster.
+        runner: Command runner.
+        which: PATH lookup function.
+    """
+    ready = 0
+    for tid in adapter_ids():
+        a = load_adapter(tid)
+        if a.status != "active":
+            rep.add("ok", f"{tid}: parked (not selectable)")
+            continue
+        # Not having a tool you do not use is fine; not having one you rely on is not.
+        lvl_missing = "fail" if tid in used else "warn"
+        if not which(a.binary):
+            rep.add(lvl_missing, f"{tid}: `{a.binary}` not found on PATH")
+            continue
+        ver = _run(runner, a.version_cmd)
+        if ver is None:
+            rep.add(lvl_missing, f"{tid}: `{' '.join(a.version_cmd)}` failed")
+            continue
+        first_line = ver.splitlines()[0] if ver else "installed"
+        line = f"{tid}: {first_line} ({a.enforcement} enforcement)"
+        if a.auth_cmd:
+            if _run(runner, a.auth_cmd) is None:
+                rep.add(
+                    lvl_missing,
+                    f"{tid}: installed but auth check `{' '.join(a.auth_cmd)}` failed (logged in?)",
+                )
+                continue
+        else:
+            line += "; auth not checked"  # e.g. claude has no cheap non-interactive check
+        rep.add("ok", line)
+        ready += 1
+    if ready < 2:
+        rep.add(
+            "warn", f"only {ready} provider(s) ready: independent cross-provider review needs two"
+        )
+
+
+def _check_roster(rep: Report, cfg: Config, path: Path) -> None:
+    """Add the roster guardrail results for a loaded config.
+
+    Args:
+        rep: Report to append to.
+        cfg: Loaded configuration.
+        path: Where the config was loaded from (shown on success).
+    """
+    r = check_roster(cfg)
+    for err in r.errors:
+        rep.add("fail", f"roster: {err}")
+    for warning in r.warnings:
+        rep.add("warn", f"roster: {warning}")
+    if not r.errors:
+        rep.add("ok", f"roster valid ({path})")
+
+
+def run_doctor(
+    config_path: Path | None = None,
+    runner: Runner = default_runner,
+    which: Which = shutil.which,
+) -> Report:
+    """Inspect the machine: CAO, provider CLIs, supporting tools and the roster.
+
+    Args:
+        config_path: Path to ``caokit.toml``; the default location if None.
+        runner: Command runner (injectable for tests).
+        which: PATH lookup (injectable for tests).
+
+    Returns:
+        A :class:`Report`; ``report.failed`` is true if anything must be fixed.
+    """
+    rep = Report()
+    cfg: Config | None = None
+    path = Path(config_path) if config_path else default_path()
+    try:
+        cfg = load_config(path)
+    except ConfigError as e:
+        # A missing config is expected before `company create`, so only warn.
+        rep.add("warn", str(e))
+    used = {b.tool for b in cfg.roles.values()} if cfg else set()
+    expected = cfg.expected_cao_version if cfg else "2.5.4"
+
+    _check_cao(rep, expected, runner, which)
+    for binary in ("tmux", "git", "uv"):
+        found = which(binary)
+        # uv is only needed to install/upgrade; tmux and git are required to run at all.
+        level = "ok" if found else ("warn" if binary == "uv" else "fail")
+        rep.add(level, f"{binary} {'found' if found else 'not found'}")
+    _check_server(rep, runner, which)
+    _check_tools(rep, used, runner, which)
+    if cfg:
+        _check_roster(rep, cfg, path)
+    return rep
+
+
+def format_report(rep: Report) -> str:
+    """Render a report as one tagged line per check.
+
+    Args:
+        rep: Report to render.
+
+    Returns:
+        Text such as ``[ ok ] cao 2.5.4`` joined by newlines.
+    """
+    tag = {"ok": "[ ok ]", "warn": "[warn]", "fail": "[FAIL]"}
+    return "\n".join(f"{tag[c.level]} {c.text}" for c in rep.checks)

caokit/gitignore.py

@@ -0,0 +1,36 @@
+"""Merge the caokit-managed block into a project .gitignore."""
+
+BEGIN = "# >>> caokit >>>"
+END = "# <<< caokit <<<"
+# Ignore everything under .company/ except contracts/, which the team tracks.
+RULES = [".company/*", "!.company/contracts/"]
+
+
+def merge_gitignore(existing: str) -> str:
+    """Return ``existing`` with the caokit block added or replaced in place.
+
+    Existing content, ordering and line endings are preserved, and the result
+    is idempotent: merging twice changes nothing.
+
+    Args:
+        existing: Current .gitignore text (may be empty).
+
+    Returns:
+        The .gitignore text containing exactly one caokit block.
+    """
+    # Match the file's own line ending so a CRLF file does not end up mixed.
+    nl = "\r\n" if "\r\n" in existing else "\n"
+    block = nl.join([BEGIN, *RULES, END])
+    lines = existing.split(nl)
+    try:
+        start = next(i for i, line in enumerate(lines) if line.strip() == BEGIN)
+        end = next(i for i, line in enumerate(lines) if i > start and line.strip() == END)
+    except StopIteration:
+        start = end = -1  # no complete block found: append a new one
+    if start >= 0:
+        # Replace our previous block (possibly stale rules) where it stands.
+        lines[start : end + 1] = block.split(nl)
+        return nl.join(lines)
+    if existing and not existing.endswith(nl):
+        existing += nl  # file lacked a trailing newline; do not glue onto the last rule
+    return existing + block + nl