caokit 0.3.0.dev0__py3-none-any.whl

caokit/company.py

@@ -0,0 +1,115 @@
+"""`caokit company create`: build, check and write caokit.toml."""
+
+from collections.abc import Callable
+from pathlib import Path
+
+from .adapters import ROLES, AdapterError, Runner, default_runner, load_adapter, validate_model
+from .config import Binding, Config, default_path, dump_config
+from .roster import check_roster
+
+
+class CompanyError(Exception):
+    """Raised when a company cannot be created (bad roster, bad model, file exists)."""
+
+
+def parse_binding(spec: str) -> Binding:
+    """Parse a ``tool`` or ``tool:model`` command-line spec.
+
+    Args:
+        spec: For example ``claude`` or ``antigravity:gemini-4-argon-high``.
+
+    Returns:
+        The binding; ``model`` is None when no ``:model`` part is given.
+
+    Raises:
+        CompanyError: The tool part is empty.
+    """
+    # partition on the first ":" only, so model IDs may not contain one but tools never do.
+    tool, _, model = spec.partition(":")
+    if not tool:
+        raise CompanyError(f"empty tool in {spec!r}")
+    return Binding(tool, model or None)
+
+
+def create_company(
+    bindings: dict[str, Binding],
+    allow_soft_engineer: bool = False,
+    allow_single_provider: bool = False,
+    allow_soft_general: bool = False,
+    runner: Runner = default_runner,
+    out: Callable[[str], None] = print,
+) -> Config:
+    """Build a config from role bindings and check every guardrail.
+
+    Roster rules and model validation both run before anything is returned, so
+    all problems are reported together. Overriding a recommended model only
+    warns; an unlisted or unverifiable model is an error.
+
+    Args:
+        bindings: Role name to binding; every role in ``ROLES`` must be present.
+        allow_soft_engineer: Accept a soft-enforcement tool as engineer.
+        allow_single_provider: Downgrade the cross-provider rule to a warning.
+        allow_soft_general: Accept a soft-enforcement tool as the General.
+        runner: Command runner used to validate models (injectable for tests).
+        out: Sink for warnings and recommendation notes.
+
+    Returns:
+        The validated :class:`Config` (not yet written to disk).
+
+    Raises:
+        CompanyError: A role is missing, the roster breaks a guardrail, or a
+            model ID is rejected. The message lists every problem.
+    """
+    cfg = Config(
+        roles=dict(bindings),
+        allow_soft_engineer=allow_soft_engineer,
+        allow_single_provider=allow_single_provider,
+        allow_soft_general=allow_soft_general,
+    )
+    errors: list[str] = [f"role {role} has no tool" for role in ROLES if role not in cfg.roles]
+    if errors:
+        raise CompanyError("\n".join(errors))  # cannot check a partial roster
+    r = check_roster(cfg)
+    errors += r.errors
+    for role in ROLES:
+        b = cfg.roles[role]
+        try:
+            a = load_adapter(b.tool)
+        except AdapterError:
+            continue  # already reported by check_roster as an unknown tool
+        rec = a.roles[role].recommended_model
+        if b.model:
+            e, w = validate_model(a, b.model, runner)
+            errors += [f"roles.{role}: {x}" for x in e]
+            r.warnings += [f"roles.{role}: {x}" for x in w]
+            if rec and b.model != rec:  # advice only: the user's choice wins
+                r.warnings.append(f"roles.{role}: {b.model} is not the recommended model ({rec})")
+        elif rec:
+            out(f"  note: roles.{role} has no model set; recommended for {a.id} is {rec}")
+    for warning in r.warnings:
+        out("WARNING: " + warning)
+    if errors:
+        raise CompanyError("\n".join(errors))
+    return cfg
+
+
+def write_company(cfg: Config, path: Path | None = None, force: bool = False) -> Path:
+    """Write ``cfg`` as caokit.toml, creating parent directories.
+
+    Args:
+        cfg: The validated configuration.
+        path: Destination (default: :func:`caokit.config.default_path`).
+        force: Overwrite an existing file.
+
+    Returns:
+        The path written.
+
+    Raises:
+        CompanyError: The file exists and ``force`` is False.
+    """
+    path = Path(path) if path else default_path()
+    if path.exists() and not force:
+        raise CompanyError(f"{path} already exists (use --force to overwrite)")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(dump_config(cfg), encoding="utf-8")
+    return path

caokit/config.py

@@ -0,0 +1,191 @@
+"""caokit.toml: load, validate and dump the company configuration."""
+
+import json
+import os
+import tomllib
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .adapters import ROLES
+from .render import validate_project_name
+
+SCHEMA = 1
+POLICY_KEYS = ("allow_soft_engineer", "allow_soft_general", "allow_single_provider")
+CAO_VERSION = "2.5.4"  # the only CAO version this kit is validated against
+
+
+class ConfigError(Exception):
+    """Raised for any problem reading or validating ``caokit.toml``."""
+
+
+@dataclass
+class Binding:
+    """The tool (and optionally model) assigned to one role.
+
+    Attributes:
+        tool: Adapter ID, e.g. ``claude``.
+        model: Model ID, or None to use the tool's own default.
+    """
+
+    tool: str
+    model: str | None = None  # None = use the tool's own default model
+
+
+@dataclass
+class Config:
+    """The whole company: one binding per role plus policy switches.
+
+    Attributes:
+        roles: Binding for each of the four roles.
+        allow_soft_engineer: Lets a soft-enforcement tool be the engineer.
+        allow_soft_general: Lets a soft-enforcement tool be the General.
+        allow_single_provider: Downgrades the cross-provider rule to a warning.
+        expected_cao_version: CAO version the kit expects; doctor warns otherwise.
+        project: Project slug when this is a project-scoped (effective) config; its
+            profiles are named ``<project>_<role>-<tool>``. None for the user-level config.
+    """
+
+    roles: dict[str, Binding]
+    allow_soft_engineer: bool = False  # lets a soft-enforcement tool be the engineer
+    allow_soft_general: bool = False  # lets a soft-enforcement tool be the General
+    allow_single_provider: bool = False  # downgrades the cross-provider rule to a warning
+    expected_cao_version: str = CAO_VERSION
+    project: str | None = None
+
+
+def default_path() -> Path:
+    """Return the default config path.
+
+    Returns:
+        ``$CAOKIT_HOME/caokit.toml`` if set, else ``~/.config/caokit/caokit.toml``.
+    """
+    home = os.environ.get("CAOKIT_HOME")
+    base = Path(home) if home else Path.home() / ".config" / "caokit"
+    return base / "caokit.toml"
+
+
+def _only(d: dict[str, Any], allowed: Iterable[str], where: str) -> None:
+    """Reject keys not in ``allowed`` so typos fail loudly instead of being ignored."""
+    allowed = set(allowed)
+    for k in d:
+        if k not in allowed:
+            raise ConfigError(f"unknown key {where}.{k}" if where else f"unknown key {k}")
+
+
+def _parse_project_name(raw: Any) -> str | None:
+    """Validate the optional ``[project] name`` table, returning the slug or None."""
+    if raw is None:
+        return None
+    _only(raw, {"name"}, "project")
+    name = raw.get("name")
+    if not isinstance(name, str):
+        raise ConfigError("project.name must be a string")
+    try:
+        return validate_project_name(name)
+    except ValueError as e:
+        raise ConfigError(str(e)) from e
+
+
+def parse_config(d: dict[str, Any]) -> Config:
+    """Validate a parsed TOML dict and build a :class:`Config`.
+
+    Tool names are not checked here; the roster rules report unknown or parked
+    tools with a clearer message.
+
+    Args:
+        d: The dict produced by parsing ``caokit.toml``.
+
+    Returns:
+        The validated configuration.
+
+    Raises:
+        ConfigError: Wrong schema, unknown/missing role, unknown key, or bad type.
+    """
+    _only(d, {"schema", "cao", "policy", "roles", "project"}, "")
+    if d.get("schema") != SCHEMA:
+        raise ConfigError(f"schema must be {SCHEMA} (got {d.get('schema')!r})")
+    cao = d.get("cao", {})
+    _only(cao, {"expected_version"}, "cao")
+    pol = d.get("policy", {})
+    _only(pol, set(POLICY_KEYS), "policy")
+    raw = d.get("roles", {})
+    for r in raw:
+        if r not in ROLES:
+            raise ConfigError(f"unknown role: roles.{r} (valid: {', '.join(ROLES)})")
+    roles: dict[str, Binding] = {}
+    for r in ROLES:
+        if r not in raw:
+            raise ConfigError(f"missing role: roles.{r}")
+        b = raw[r]
+        _only(b, {"tool", "model"}, "roles." + r)
+        if not isinstance(b.get("tool"), str) or not b["tool"]:
+            raise ConfigError(f"roles.{r}.tool must be a non-empty string")
+        m = b.get("model")
+        if m is not None and (not isinstance(m, str) or not m):
+            raise ConfigError(f"roles.{r}.model must be a non-empty string")
+        roles[r] = Binding(b["tool"], m)
+    for k in POLICY_KEYS:
+        if not isinstance(pol.get(k, False), bool):
+            raise ConfigError(f"policy.{k} must be true or false")
+    return Config(
+        roles=roles,
+        allow_soft_engineer=pol.get("allow_soft_engineer", False),
+        allow_soft_general=pol.get("allow_soft_general", False),
+        allow_single_provider=pol.get("allow_single_provider", False),
+        expected_cao_version=cao.get("expected_version", CAO_VERSION),
+        project=_parse_project_name(d.get("project")),
+    )
+
+
+def load_config(path: Path | None = None) -> Config:
+    """Read and validate the config file.
+
+    Args:
+        path: File to read; the default location if None.
+
+    Returns:
+        The validated configuration.
+
+    Raises:
+        ConfigError: The file is missing, is not valid TOML, or fails validation.
+    """
+    path = Path(path) if path else default_path()
+    if not path.is_file():
+        raise ConfigError(f"config not found: {path} (run `caokit company create`)")
+    try:
+        return parse_config(tomllib.loads(path.read_text(encoding="utf-8")))
+    except ValueError as e:  # TOMLDecodeError subclasses ValueError
+        raise ConfigError(f"invalid TOML in {path}: {e}") from e
+
+
+def dump_config(c: Config) -> str:
+    """Serialise a config to TOML text (hand-rolled: stdlib can only read TOML).
+
+    Args:
+        c: The configuration to write.
+
+    Returns:
+        TOML text that :func:`parse_config` round-trips.
+    """
+    q = json.dumps  # JSON string escaping is valid TOML basic-string escaping
+    out = [
+        f"schema = {SCHEMA}",
+        "",
+        "[cao]",
+        f"expected_version = {q(c.expected_cao_version)}",
+        "",
+        "[policy]",
+        f"allow_soft_engineer = {str(c.allow_soft_engineer).lower()}",
+        f"allow_soft_general = {str(c.allow_soft_general).lower()}",
+        f"allow_single_provider = {str(c.allow_single_provider).lower()}",
+    ]
+    if c.project:
+        out[2:2] = ["[project]", f"name = {q(c.project)}", ""]
+    for r in ROLES:
+        b = c.roles[r]
+        out += ["", f"[roles.{r}]", f"tool = {q(b.tool)}"]
+        if b.model:  # omit entirely when unset so the tool default applies
+            out.append(f"model = {q(b.model)}")
+    return "\n".join(out) + "\n"

caokit/data/adapters/antigravity.toml

@@ -0,0 +1,35 @@
+id = "antigravity"
+cao_provider = "antigravity_cli"
+enforcement = "soft"
+status = "active"
+default_vendor = "google"
+
+[detect]
+binary = "agy"
+version_cmd = ["agy", "--version"]
+auth_cmd = ["agy", "models"]       # succeeds only when logged in
+
+[models]
+source = "cmd"
+list_cmd = ["agy", "models"]       # first tab-separated column is the model ID
+vendor_map = { "gemini-" = "google", "claude-" = "anthropic", "gpt-" = "openai" }
+
+[frontmatter]
+
+[roles.general]
+can_fill = "yes"                   # soft enforcement still requires --allow-soft-general
+
+[roles.engineer]
+can_fill = "yes"                   # soft enforcement still requires --allow-soft-engineer
+recommended_model = "gemini-4-argon-high"
+
+[roles.scout]
+can_fill = "yes"
+recommended_model = "gemini-3.8-flash-medium"
+
+[roles.inspector]
+can_fill = "yes"
+recommended_model = "gemini-4-argon-high"
+
+[notes]
+text = "CAO launches Antigravity with `--dangerously-skip-permissions`, so the tool limits in this profile are advisory only. Follow the boundaries above exactly; nothing enforces them."

caokit/data/adapters/claude.toml

@@ -0,0 +1,38 @@
+id = "claude"
+cao_provider = "claude_code"
+enforcement = "native"
+status = "active"
+default_vendor = "anthropic"
+
+[detect]
+binary = "claude"
+version_cmd = ["claude", "--version"]
+auth_cmd = []                      # no cheap non-interactive auth check
+
+[models]
+source = "shape"                   # no `claude models` command exists
+aliases = ["sonnet", "opus", "haiku", "fable"]
+shape = "^claude-[A-Za-z0-9.\\[\\]-]+$"
+vendor_map = { "" = "anthropic" }
+
+[frontmatter]
+permissionMode = "auto"
+
+[roles.general]
+can_fill = "yes"
+recommended_model = "sonnet"
+
+[roles.engineer]
+can_fill = "yes"
+recommended_model = "opus"
+
+[roles.scout]
+can_fill = "yes"
+recommended_model = "sonnet"
+
+[roles.inspector]
+can_fill = "yes"
+recommended_model = "sonnet"
+
+[notes]
+text = ""

caokit/data/adapters/codex.toml

@@ -0,0 +1,33 @@
+id = "codex"
+cao_provider = "codex"
+enforcement = "soft"
+status = "parked"                  # not selectable; kept as metadata only
+default_vendor = "openai"
+
+[detect]
+binary = "codex"
+version_cmd = ["codex", "--version"]
+auth_cmd = ["codex", "login", "status"]
+
+[models]
+source = "shape"
+aliases = []
+shape = "^[A-Za-z0-9.-]+$"
+vendor_map = { "" = "openai" }
+
+[frontmatter]
+
+[roles.general]
+can_fill = "no"
+
+[roles.engineer]
+can_fill = "no"
+
+[roles.scout]
+can_fill = "no"
+
+[roles.inspector]
+can_fill = "no"
+
+[notes]
+text = ""

caokit/data/roles/engineer.md

@@ -0,0 +1,90 @@
+---
+description: "Engineer: scoped implementation, tests, debugging; runs only the authorised commands"
+role: developer
+skills: []
+allowedTools:
+  - "fs_read"
+  - "fs_list"
+  - "fs_write"
+  - "execute_bash"
+  - "@cao-mcp-server"
+mcpServers:
+  cao-mcp-server:
+    type: stdio
+    command: cao-mcp-server
+    args: []
+---
+
+# Engineer
+
+## Identity
+
+You are the implementation engineer. The General owns delegation and the human owns final approval. Any source change you make is reviewed by the `inspector`, which runs on a different tool (see `.company/ROSTER.md`).
+
+## Before working
+
+1. Read `.company/COMPANY.md`.
+2. Read `.company/contracts/`.
+3. Read the exact task file named in the assignment.
+4. Restate internally the allowed paths, forbidden paths, deliverables, and acceptance checks.
+5. If the task is ambiguous or exceeds its boundary, stop and message the General.
+
+## Engineering rules
+
+- Inspect before editing.
+- Change only the assigned scope.
+- Prefer the smallest coherent change.
+- Add or update tests when source changes are authorized.
+- Run the task's "Authorised validation commands" exactly as written, and record each command with its real output. Do not skip an authorised check out of caution.
+- Run no other commands for validation or tidying: no `rm`, no cleanup of generated files, no git commands that change state (except the commit in Worktree mode below). If an authorised command leaves files behind (for example `__pycache__/`), leave them and report it, so the General can fix the task's command.
+- Never deploy, merge, push, rewrite Git history, alter production data, read secrets, or contact external systems.
+- Do not install packages, change lockfiles, or use network access unless the task explicitly authorizes it.
+- Do not create or delegate to another agent, including Claude Code's own subagent tool.
+- Do not claim a command passed unless you actually ran it and saw a successful result.
+
+## Worktree mode
+
+You are in worktree mode when your working directory contains `/.cao/worktrees/`. The project root is the part of the path before `/.cao/worktrees/`.
+
+- Your working directory is a private checkout on its own branch. Edit source only there.
+- `.company/` is git-ignored and does not exist in your checkout. Read the contracts and the task file, and write your artifact, under the project root's `.company/` (absolute paths), never under your checkout.
+- Before editing, run `git rev-parse HEAD` and record it in your artifact as **Base commit**. Read the contracts, the task file and the source with your file tools, not with `ls`, `cat` or `pwd`; those are outside the authorised commands.
+- When your work is done and the authorised checks pass, run `git add -A` and then `git commit -m "<TASK-ID>: <task title>"`, then `git rev-parse HEAD` and record the hash in your artifact as **Commit**. CAO discards uncommitted work when your terminal is deleted. Commit again, never amend, when asked to rework.
+- These are the only state-changing git commands you may run, and only here. Never push, merge, rebase, reset, checkout another branch or touch other worktrees.
+- Report `BLOCKED` instead of `COMPLETED` if the commit fails.
+
+## Smoke-test restriction
+
+For TASK-0001 (smoke test), do not modify application source. Write only the contracted artifact under `.company/artifacts/`.
+
+## Required completion artifact
+
+Unless the task says otherwise, write:
+
+```text
+.company/artifacts/<TASK-ID>-engineer.md
+```
+
+Include:
+
+- scope inspected,
+- architecture summary,
+- files or modules examined,
+- work performed,
+- every command you ran, each with its real output (a **Commands run** section),
+- changed files,
+- risks,
+- unresolved questions,
+- recommended next action.
+
+## Callback
+
+When assigned asynchronously, call `send_message` without `receiver_id` so CAO routes the callback to the assigning General. Send only:
+
+- task ID,
+- `COMPLETED`, `BLOCKED`, or `FAILED`,
+- absolute artifact path,
+- up to five findings,
+- blocker or decision required.
+
+Do not paste the full artifact into the message.