coding-os 0.3.7__tar.gz → 0.3.8__tar.gz

{coding_os-0.3.7 → coding_os-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-os
-Version: 0.3.7
+Version: 0.3.8
 Summary: The cognitive operating system that gives AI agents memory, structure, and discipline
 Author-email: Kourosh Ebrahimzadeh <info@coding-os.dev>
 License-Expression: Apache-2.0

{coding_os-0.3.7 → coding_os-0.3.8}/coding_os.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-os
-Version: 0.3.7
+Version: 0.3.8
 Summary: The cognitive operating system that gives AI agents memory, structure, and discipline
 Author-email: Kourosh Ebrahimzadeh <info@coding-os.dev>
 License-Expression: Apache-2.0

{coding_os-0.3.7 → coding_os-0.3.8}/coding_os.egg-info/SOURCES.txt

@@ -92,6 +92,7 @@ src/cli/skills_list.py
 src/cli/stack_lint.py
 src/cli/stack_registry.py
 src/cli/subsystems.py
+src/cli/supervision_commands.py
 src/cli/sync_all.py
 src/cli/tail_command.py
 src/cli/update.py
@@ -553,6 +554,7 @@ src/core/thinking_os/impact.py
 src/core/thinking_os/memory_gc.py
 src/core/thinking_os/migrator_embeddings.py
 src/core/thinking_os/precision.py
+src/core/thinking_os/project_settings.py
 src/core/thinking_os/record_outcome.py
 src/core/thinking_os/repair.py
 src/core/thinking_os/retrieval_quality.py

{coding_os-0.3.7 → coding_os-0.3.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "coding-os"
-version = "0.3.7"
+version = "0.3.8"
 description = "The cognitive operating system that gives AI agents memory, structure, and discipline"
 readme = "README.md"
 requires-python = ">=3.10"

{coding_os-0.3.7 → coding_os-0.3.8}/src/cli/main.py

@@ -1297,11 +1297,13 @@ from cli.module_commands import module_group as module_group_cmd  # noqa: E402
 from cli.preset_commands import preset_group as preset_group_cmd  # noqa: E402
 from cli.skill_commands import skill_group as skill_group_cmd  # noqa: E402
 from cli.stack_lint import stack_lint as stack_lint_cmd  # noqa: E402
+from cli.supervision_commands import supervision_group as supervision_group_cmd  # noqa: E402
 
 cli.add_command(module_group_cmd)
 cli.add_command(preset_group_cmd)
 cli.add_command(skill_group_cmd)
 cli.add_command(stack_lint_cmd)
+cli.add_command(supervision_group_cmd)
 
 # Durable error/log query CLI (cos errors / cos logs).
 try:

coding_os-0.3.8/src/cli/supervision_commands.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from thinking_os.supervision import policy_snapshot, update_policy
+
+
+def _project_root(raw: str) -> Path:
+    root = Path(raw).resolve()
+    if not (root / ".coding-os").is_dir():
+        raise click.ClickException(
+            f"{root} is not a coding-os project (.coding-os/ missing) — run from the project root."
+        )
+    return root
+
+
+def _emit_snapshot(root: Path, output_format: str) -> None:
+    snapshot = policy_snapshot(root)
+    if output_format == "json":
+        click.echo(json.dumps(snapshot, indent=2))
+        return
+    policy = snapshot["policy"]
+    click.echo(f"Supervision: {'enabled' if policy['enabled'] else 'disabled'}")
+    click.echo(
+        f"Mode: {policy['mode']} · threshold: {policy['complexity_threshold']} · "
+        f"fallback: {policy['fallback_policy']} · parallel: {policy['max_parallel']}"
+    )
+    cooldown = policy["cooldown"]
+    click.echo(
+        f"Cooldown: {cooldown['default_seconds']}s default · {cooldown['maximum_seconds']}s maximum"
+    )
+    orchestrator = policy["orchestrator"]
+    click.echo(
+        "Orchestrator: "
+        + "/".join(
+            (
+                orchestrator["adapter"] or "current-adapter",
+                orchestrator["model"] or "default-model",
+                orchestrator["effort"] or "default-effort",
+            )
+        )
+    )
+    roles = policy["roles"]
+    click.echo("Roles: " + (", ".join(sorted(roles)) if roles else "none"))
+    adapters = snapshot["adapters"]
+    click.echo("Eligible adapters: " + (", ".join(row["id"] for row in adapters) or "none"))
+    click.echo(f"Settings: {snapshot['settings_path']}")
+
+
+def _update(root: Path, patch: dict, **kwargs) -> None:
+    try:
+        update_policy(root, patch, **kwargs)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@click.group("supervision")
+def supervision_group() -> None:
+    """Inspect and configure agent supervision without Hub."""
+
+
+@supervision_group.command("show")
+@click.option("-d", "--project-dir", default=".", show_default=True, type=click.Path())
+@click.option("--format", "output_format", type=click.Choice(["text", "json"]), default="text")
+def supervision_show(project_dir: str, output_format: str) -> None:
+    """Show the normalized project policy and eligible adapters."""
+    _emit_snapshot(_project_root(project_dir), output_format)
+
+
+def _toggle(project_dir: str, enabled: bool, output_format: str) -> None:
+    root = _project_root(project_dir)
+    _update(root, {"enabled": enabled})
+    _emit_snapshot(root, output_format)
+
+
+@supervision_group.command("enable")
+@click.option("-d", "--project-dir", default=".", show_default=True, type=click.Path())
+@click.option("--format", "output_format", type=click.Choice(["text", "json"]), default="text")
+def supervision_enable(project_dir: str, output_format: str) -> None:
+    """Enable supervision for this project."""
+    _toggle(project_dir, True, output_format)
+
+
+@supervision_group.command("disable")
+@click.option("-d", "--project-dir", default=".", show_default=True, type=click.Path())
+@click.option("--format", "output_format", type=click.Choice(["text", "json"]), default="text")
+def supervision_disable(project_dir: str, output_format: str) -> None:
+    """Disable supervision while preserving its policy."""
+    _toggle(project_dir, False, output_format)
+
+
+@supervision_group.command("set")
+@click.option("-d", "--project-dir", default=".", show_default=True, type=click.Path())
+@click.option("--mode", type=click.Choice(["explicit", "suggest", "adaptive"]))
+@click.option(
+    "--complexity-threshold",
+    type=click.Choice(["CLEAR", "COMPLICATED", "COMPLEX", "CHAOTIC"]),
+)
+@click.option(
+    "--fallback-policy",
+    type=click.Choice(["fail_closed", "same_adapter_default", "next_eligible"]),
+)
+@click.option("--max-parallel", type=click.IntRange(1, 16))
+@click.option("--cooldown-default-seconds", type=click.IntRange(1, 86400))
+@click.option("--cooldown-maximum-seconds", type=click.IntRange(1, 604800))
+@click.option("--orchestrator-adapter")
+@click.option("--orchestrator-model")
+@click.option("--orchestrator-effort")
+@click.option("--clear-orchestrator", is_flag=True)
+@click.option("--role")
+@click.option("--role-adapter")
+@click.option("--role-model")
+@click.option("--role-effort")
+@click.option("--clear-role", is_flag=True)
+@click.option("--format", "output_format", type=click.Choice(["text", "json"]), default="text")
+def supervision_set(
+    project_dir: str,
+    mode: str | None,
+    complexity_threshold: str | None,
+    fallback_policy: str | None,
+    max_parallel: int | None,
+    cooldown_default_seconds: int | None,
+    cooldown_maximum_seconds: int | None,
+    orchestrator_adapter: str | None,
+    orchestrator_model: str | None,
+    orchestrator_effort: str | None,
+    clear_orchestrator: bool,
+    role: str | None,
+    role_adapter: str | None,
+    role_model: str | None,
+    role_effort: str | None,
+    clear_role: bool,
+    output_format: str,
+) -> None:
+    """Partially update routing, cooldown, orchestrator, or one role policy."""
+    root = _project_root(project_dir)
+    patch: dict = {}
+    for key, value in (
+        ("mode", mode),
+        ("complexity_threshold", complexity_threshold),
+        ("fallback_policy", fallback_policy),
+        ("max_parallel", max_parallel),
+    ):
+        if value is not None:
+            patch[key] = value
+    cooldown = {
+        key: value
+        for key, value in (
+            ("default_seconds", cooldown_default_seconds),
+            ("maximum_seconds", cooldown_maximum_seconds),
+        )
+        if value is not None
+    }
+    if cooldown:
+        patch["cooldown"] = cooldown
+    orchestrator = {
+        key: value
+        for key, value in (
+            ("adapter", orchestrator_adapter),
+            ("model", orchestrator_model),
+            ("effort", orchestrator_effort),
+        )
+        if value is not None
+    }
+    if orchestrator:
+        patch["orchestrator"] = orchestrator
+    role_values = {
+        key: value
+        for key, value in (
+            ("adapter", role_adapter),
+            ("model", role_model),
+            ("effort", role_effort),
+        )
+        if value is not None
+    }
+    if (role_values or clear_role) and not role:
+        raise click.UsageError("--role is required with role options or --clear-role")
+    if role_values and role:
+        patch["roles"] = {role: role_values}
+    if not patch and not clear_role and not clear_orchestrator:
+        raise click.UsageError("provide at least one setting to update")
+    _update(
+        root,
+        patch,
+        clear_role=(role or "") if clear_role else "",
+        clear_orchestrator=clear_orchestrator,
+    )
+    _emit_snapshot(root, output_format)

{coding_os-0.3.7 → coding_os-0.3.8}/src/core/subsystems.yaml

@@ -152,7 +152,7 @@ modules:
     # The reasoning-assist tool surface: role composition, formula dispatch,
     # supervision, model/skill routing, situation detect. cos_classify_prompt
     # (Record Gate, core loop) + cos_health (diagnostic) stay KERNEL by design.
-    tools: ["cos_dispatch_*", "cos_route_*", cos_compose_chain, cos_supervise, cos_supervise_record_output, cos_role_info, cos_situation_detect, cos_takeover, cos_analyze_task, cos_ambiguity_check, cos_backtrack_log, cos_discovery]
+    tools: ["cos_dispatch_*", "cos_route_*", cos_compose_chain, cos_supervise, cos_supervise_record_output, cos_supervision_config, cos_role_info, cos_situation_detect, cos_takeover, cos_analyze_task, cos_ambiguity_check, cos_backtrack_log, cos_discovery]
     # /compose is the role-chain composition surface; /role-* commands map from
     # thinking_os/agents/ (a separate source) and stay always-on (Rule 22 — not
     # worth the agents/ source-mapping to gate a low-frequency advanced surface).

coding_os-0.3.8/src/core/thinking_os/project_settings.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import json
+import os
+import tempfile
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+
+class SettingsConflictError(ValueError):
+    pass
+
+
+def project_settings_path(project_root: Path | None = None) -> Path:
+    if project_root is not None:
+        return project_root.resolve() / ".coding-os" / "hub-settings.json"
+    state_dir = os.environ.get("COS_STATE_DIR")
+    if state_dir:
+        return Path(state_dir).resolve() / "hub-settings.json"
+    configured_root = os.environ.get("COS_PROJECT_ROOT")
+    root = Path(configured_root).resolve() if configured_root else Path.cwd().resolve()
+    return root / ".coding-os" / "hub-settings.json"
+
+
+def read_settings(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise SettingsConflictError(
+            f"{path} is present but unreadable; refusing to overwrite it: {exc}"
+        ) from exc
+    if not isinstance(data, dict):
+        raise SettingsConflictError(f"{path} must contain a JSON object")
+    return data
+
+
+def write_settings(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".hub-settings.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, indent=2)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except Exception:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+
+
+@contextlib.contextmanager
+def settings_lock(path: Path) -> Iterator[None]:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lock_path = path.with_name("hub-settings.lock")
+    with lock_path.open("w", encoding="utf-8") as handle:
+        try:
+            fcntl.flock(handle, fcntl.LOCK_EX)
+            yield
+        finally:
+            fcntl.flock(handle, fcntl.LOCK_UN)

{coding_os-0.3.7 → coding_os-0.3.8}/src/core/thinking_os/supervision.py

@@ -1,15 +1,23 @@
 from __future__ import annotations
 
-import json
+import copy
 import logging
 import os
 import sqlite3
 import time
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
 
 from thinking_os.adapter_registry import AdapterRecord, configured_adapter_ids, load_adapter_records
+from thinking_os.project_settings import (
+    project_settings_path,
+    read_settings,
+    settings_lock,
+    write_settings,
+)
 
 logger = logging.getLogger("coding_os.supervision")
 
@@ -26,6 +34,35 @@ DEFAULT_MODEL_ROUTING: dict[str, Any] = {
 }
 
 
+class AdapterTargetPolicy(BaseModel):
+    adapter: str = ""
+    model: str = ""
+    effort: str = ""
+
+
+class CooldownPolicy(BaseModel):
+    default_seconds: int = Field(default=300, ge=1, le=86400)
+    maximum_seconds: int = Field(default=3600, ge=1, le=604800)
+
+    @model_validator(mode="after")
+    def validate_range(self):
+        if self.maximum_seconds < self.default_seconds:
+            raise ValueError("maximum_seconds must be greater than or equal to default_seconds")
+        return self
+
+
+class ModelRoutingPolicy(BaseModel):
+    enabled: bool
+    orchestrator_model: str = ""
+    mode: Literal["explicit", "suggest", "adaptive"] = "explicit"
+    complexity_threshold: Literal["CLEAR", "COMPLICATED", "COMPLEX", "CHAOTIC"] = "COMPLICATED"
+    fallback_policy: Literal["fail_closed", "same_adapter_default", "next_eligible"] = "fail_closed"
+    max_parallel: int = Field(default=3, ge=1, le=16)
+    orchestrator: AdapterTargetPolicy = Field(default_factory=AdapterTargetPolicy)
+    roles: dict[str, AdapterTargetPolicy] = Field(default_factory=dict)
+    cooldown: CooldownPolicy = Field(default_factory=CooldownPolicy)
+
+
 @dataclass(frozen=True)
 class HealthDecision:
     allowed: bool
@@ -40,30 +77,96 @@ def current_project_root() -> Path:
     return Path(value).resolve() if value else Path.cwd().resolve()
 
 
-def _settings_path(project_root: Path | None = None) -> Path:
-    if project_root is not None:
-        return project_root / ".coding-os" / "hub-settings.json"
-    state_dir = os.environ.get("COS_STATE_DIR")
-    if state_dir:
-        return Path(state_dir) / "hub-settings.json"
-    return current_project_root() / ".coding-os" / "hub-settings.json"
+def normalize_policy(raw: dict[str, Any] | None = None) -> dict[str, Any]:
+    source = raw if isinstance(raw, dict) else {}
+    merged = {**copy.deepcopy(DEFAULT_MODEL_ROUTING), **source}
+    for key in ("orchestrator", "cooldown"):
+        value = source.get(key)
+        merged[key] = {
+            **copy.deepcopy(DEFAULT_MODEL_ROUTING[key]),
+            **(value if isinstance(value, dict) else {}),
+        }
+    roles = source.get("roles")
+    merged["roles"] = roles if isinstance(roles, dict) else {}
+    if not merged["orchestrator"].get("model") and merged.get("orchestrator_model"):
+        merged["orchestrator"]["model"] = merged["orchestrator_model"]
+    if merged["orchestrator"].get("model"):
+        merged["orchestrator_model"] = merged["orchestrator"]["model"]
+    return ModelRoutingPolicy.model_validate(merged).model_dump()
 
 
 def load_policy(project_root: Path | None = None) -> dict[str, Any]:
-    raw: dict[str, Any] = {}
     try:
-        data = json.loads(_settings_path(project_root).read_text(encoding="utf-8"))
-        if isinstance(data, dict) and isinstance(data.get("model_routing"), dict):
-            raw = data["model_routing"]
-    except (OSError, ValueError):
-        pass
-    policy = {**DEFAULT_MODEL_ROUTING, **raw}
-    for key in ("orchestrator", "cooldown"):
-        base = DEFAULT_MODEL_ROUTING[key]
-        value = raw.get(key)
-        policy[key] = {**base, **(value if isinstance(value, dict) else {})}
-    policy["roles"] = raw.get("roles") if isinstance(raw.get("roles"), dict) else {}
-    return policy
+        data = read_settings(project_settings_path(project_root))
+        raw = data.get("model_routing")
+        return normalize_policy(raw if isinstance(raw, dict) else {})
+    except ValueError as exc:
+        logger.debug("supervision settings unavailable: %s", exc)
+        return normalize_policy()
+
+
+def update_policy(
+    project_root: Path,
+    patch: dict[str, Any],
+    *,
+    clear_role: str = "",
+    clear_orchestrator: bool = False,
+) -> dict[str, Any]:
+    root = project_root.resolve()
+    state_dir = root / ".coding-os"
+    if not state_dir.is_dir():
+        raise ValueError(f"{root} is not a coding-os project (.coding-os/ missing)")
+    path = project_settings_path(root)
+    with settings_lock(path):
+        settings = read_settings(path)
+        raw_policy = settings.get("model_routing", {})
+        if not isinstance(raw_policy, dict):
+            raise ValueError("model_routing must be a JSON object")
+        current = normalize_policy(raw_policy)
+        candidate = {**current, **patch}
+        for key in ("orchestrator", "cooldown"):
+            value = patch.get(key)
+            candidate[key] = {
+                **current[key],
+                **(value if isinstance(value, dict) else {}),
+            }
+        roles = {**current["roles"]}
+        role_patch = patch.get("roles")
+        if isinstance(role_patch, dict):
+            for role, target in role_patch.items():
+                if not role.strip():
+                    raise ValueError("role id must not be empty")
+                if not isinstance(target, dict):
+                    raise ValueError(f"role {role!r} must be an object")
+                roles[role] = {**roles.get(role, {}), **target}
+        if clear_role:
+            roles.pop(clear_role, None)
+        candidate["roles"] = roles
+        if clear_orchestrator:
+            candidate["orchestrator"] = copy.deepcopy(DEFAULT_MODEL_ROUTING["orchestrator"])
+            candidate["orchestrator_model"] = ""
+        normalized = normalize_policy(candidate)
+        settings["model_routing"] = normalized
+        write_settings(path, settings)
+    return normalized
+
+
+def policy_snapshot(project_root: Path | None = None) -> dict[str, Any]:
+    root = (project_root or current_project_root()).resolve()
+    records = eligible_records(root)
+    return {
+        "policy": load_policy(root),
+        "settings_path": str(project_settings_path(root)),
+        "adapters": [
+            {
+                "id": record.id,
+                "models": [str(model.get("id")) for model in record.models if model.get("id")],
+                "efforts": list(record.efforts),
+                "capabilities": sorted(record.capabilities),
+            }
+            for record in records
+        ],
+    }
 
 
 def enabled(project_root: Path | None = None) -> bool:

{coding_os-0.3.7 → coding_os-0.3.8}/src/core/thinking_os/tools/cognition.py

@@ -1894,8 +1894,108 @@ def register_cos_classify_prompt(mcp, db_path):
     return cos_classify_prompt
 
 
+def register_cos_supervision_config(mcp, db_path):
+    @mcp.tool(
+        name="cos_supervision_config",
+        description=(
+            "Show, enable, disable, or partially configure the current project's "
+            "adapter-neutral supervision policy without requiring Hub."
+        ),
+    )
+    @safe_tool
+    def cos_supervision_config(
+        action: str = "show",
+        mode: str = "",
+        complexity_threshold: str = "",
+        fallback_policy: str = "",
+        max_parallel: int = 0,
+        cooldown_default_seconds: int = 0,
+        cooldown_maximum_seconds: int = 0,
+        orchestrator_adapter: str = "",
+        orchestrator_model: str = "",
+        orchestrator_effort: str = "",
+        clear_orchestrator: bool = False,
+        role: str = "",
+        role_adapter: str = "",
+        role_model: str = "",
+        role_effort: str = "",
+        clear_role: bool = False,
+    ) -> str:
+        """Manage the normalized project supervision policy without Hub."""
+        from thinking_os import supervision
+
+        normalized_action = action.strip().lower()
+        if normalized_action not in {"show", "enable", "disable", "set"}:
+            return fail("validation", "action must be show, enable, disable, or set")
+        root = supervision.current_project_root()
+        if normalized_action == "show":
+            return ok(supervision.policy_snapshot(root), meta={"layer": "routing"})
+        if normalized_action in {"enable", "disable"}:
+            try:
+                supervision.update_policy(root, {"enabled": normalized_action == "enable"})
+            except ValueError as exc:
+                return fail("validation", str(exc))
+            return ok(supervision.policy_snapshot(root), meta={"layer": "routing"})
+
+        patch: dict[str, object] = {}
+        for key, value in (
+            ("mode", mode),
+            ("complexity_threshold", complexity_threshold),
+            ("fallback_policy", fallback_policy),
+        ):
+            if value:
+                patch[key] = value
+        if max_parallel:
+            patch["max_parallel"] = max_parallel
+        cooldown: dict[str, int] = {}
+        if cooldown_default_seconds:
+            cooldown["default_seconds"] = cooldown_default_seconds
+        if cooldown_maximum_seconds:
+            cooldown["maximum_seconds"] = cooldown_maximum_seconds
+        if cooldown:
+            patch["cooldown"] = cooldown
+        orchestrator = {
+            key: value
+            for key, value in (
+                ("adapter", orchestrator_adapter),
+                ("model", orchestrator_model),
+                ("effort", orchestrator_effort),
+            )
+            if value
+        }
+        if orchestrator:
+            patch["orchestrator"] = orchestrator
+        role_target = {
+            key: value
+            for key, value in (
+                ("adapter", role_adapter),
+                ("model", role_model),
+                ("effort", role_effort),
+            )
+            if value
+        }
+        if (role_target or clear_role) and not role.strip():
+            return fail("validation", "role is required with role fields or clear_role")
+        if role_target:
+            patch["roles"] = {role.strip(): role_target}
+        if not patch and not clear_role and not clear_orchestrator:
+            return fail("validation", "set requires at least one policy field")
+        try:
+            supervision.update_policy(
+                root,
+                patch,
+                clear_role=role.strip() if clear_role else "",
+                clear_orchestrator=clear_orchestrator,
+            )
+        except ValueError as exc:
+            return fail("validation", str(exc))
+        return ok(supervision.policy_snapshot(root), meta={"layer": "routing"})
+
+    return cos_supervision_config
+
+
 def register_all(mcp, db_path: str) -> None:
-    """Register all 15 cognition tools with the MCP server."""
+    """Register all cognition tools with the MCP server."""
     register_cos_supervise(mcp, db_path)
     register_cos_supervise_record_output(mcp, db_path)
     register_cos_dispatch_formula(mcp, db_path)
@@ -1914,3 +2014,4 @@ def register_all(mcp, db_path: str) -> None:
     register_cos_dispatch_parallel_run(mcp, db_path)
     # auto-Classify (eliminates manual gate recording)
     register_cos_classify_prompt(mcp, db_path)
+    register_cos_supervision_config(mcp, db_path)