coding-os 0.3.2__py3-none-any.whl

adapters/claude/update_mcp_json.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""
+Coding OS — Claude adapter: idempotent .mcp.json updater.
+
+PURPOSE:
+    Add/refresh the `coding-os` entry in a project's .mcp.json. Shipped as
+    a standalone script (not a heredoc inside install.sh) because Homebrew
+    bash 5.3.9 deadlocks `python3 - <<HEREDOC` setups — sample(1) shows
+    `heredoc_write` blocked indefinitely before fork. System /bin/bash
+    (3.2) and Linux bash 5.0/5.2 are unaffected, but `#!/usr/bin/env bash`
+    resolves to the buggy Homebrew binary on macs that have it. Codex
+    adapter ships its updater the same way for the same reason.
+
+USAGE:
+    python3 update_mcp_json.py <mcp_file_path> <coding_os_root>
+
+OUTPUT:
+    Writes the updated .mcp.json. Exits 0 on success, 1 on bad JSON in
+    the existing file.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from pathlib import Path
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 3:
+        sys.stderr.write(f"usage: {argv[0]} <mcp_file_path> <coding_os_root>\n")
+        return 2
+
+    mcp_path = Path(argv[1])
+    cos_root = argv[2]
+
+    # Prefer cos-mcp-start (fast-path entry, ~120ms quicker cold boot)
+    # over `cos server-start`. Both are installed by the same wheel, but
+    # the fast-path skips cli.main's heavy subcommand imports.
+    has_fast = shutil.which("cos-mcp-start") is not None
+    has_cos = shutil.which("cos") is not None
+
+    try:
+        with mcp_path.open() as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        data = {}
+    except json.JSONDecodeError as exc:
+        sys.stderr.write(f"  ERROR: {mcp_path} is not valid JSON: {exc}\n")
+        return 1
+
+    data.setdefault("mcpServers", {})
+    if has_fast:
+        data["mcpServers"]["coding-os"] = {
+            "command": "cos-mcp-start",
+            "args": [],
+        }
+    elif has_cos:
+        data["mcpServers"]["coding-os"] = {
+            "command": "cos",
+            "args": ["server-start"],
+        }
+    else:
+        # Fallback before `uv tool install` puts `cos` on PATH. The cwd
+        # placeholder lets VSCode resolve it per-workspace.
+        data["mcpServers"]["coding-os"] = {
+            "command": "uv",
+            "args": [
+                "run",
+                "--directory",
+                f"{cos_root}/core/thinking_os",
+                "python",
+                "server.py",
+            ],
+            "cwd": "${workspaceFolder}",
+        }
+
+    with mcp_path.open("w") as f:
+        json.dump(data, f, indent=2)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

adapters/codex/adapter.yaml

@@ -0,0 +1,254 @@
+version: 1
+id: codex
+label: "OpenAI Codex CLI"
+
+# Hub chat model picker — adapter→models SSOT (served by /api/config/adapters).
+# runtime: roadmap ⇒ declared but not yet runnable inside Hub chat (Claude SDK
+# only today). Models intentionally empty — no fabricated IDs (P7 no-guessing).
+runtime: roadmap
+models: []
+
+presence:
+  signal: hook_timestamps
+  hub_glyph: "Cx"
+  hub_color: "#0891b2"
+  presence_events:
+    - SessionStart
+    - UserPromptSubmit
+    - PreToolUse
+    - PostToolUse
+    - SubagentStart
+    - SubagentStop
+    - Stop
+    - SessionEnd
+settings_file: ".codex/hooks.json"
+hooks_dir: ".codex/hooks"
+rules_dir: ".codex/rules"
+skills_dir: ".codex/skills"
+commands_dir: ".codex/commands"
+sourced_hooks: [cos-env.sh]
+supports_rules: true
+supports_settings_json: true
+install_script: install.sh
+
+cli_binary: codex
+sdk_package: openai-codex
+sdk_optional_extra: codex-sdk
+auth_env_vars: [CODEX_API_KEY, OPENAI_API_KEY]
+chat_provider: chat_provider.py
+
+# Env vars the Codex CLI runtime exports.  Same purpose as the field on
+# the Claude adapter — keeps agent detection data-driven (rule #11).
+runtime_env_markers:
+  - CODEX_SESSION_ID
+  - CODEX_AGENT_DIR
+  - CODEX_HOME
+
+# Per-panel session identity — see adapters/claude/adapter.yaml for the
+# contract. Codex CLI exports CODEX_SESSION_ID to hook subprocesses; the
+# stdin payload also carries session_id per the OpenAI Codex hook spec.
+runtime_session_marker:
+  stdin_field: session_id
+  env_vars:
+    - CODEX_SESSION_ID
+
+# Helper script invoked by `cos setup-mcp` / `cli/main.py` to write Codex
+# MCP config safely (TOML-aware).
+mcp_helper: ensure_codex_mcp.py
+
+# MCP launch metadata consumed by cli/doctor.py::_load_coding_os_mcp_launch
+# (C15 check). Data-driven so tests/test_no_hardcoded_stacks.py stays green.
+mcp_launch:
+  loader: codex_toml       # maps to cli.doctor._load_codex
+  config_paths:
+    - scope: project
+      path: .codex/config.toml
+    - scope: home
+      path: .codex/config.toml
+default_settings: {}
+
+hook_registry_output: hooks.template.json
+
+hook_capabilities:
+  PreToolUse:
+    matchers: [Bash, Edit, Read, "mcp__coding-os__cos_task_move", "mcp__coding-os__cos_task_create", "mcp__coding-os__cos_work_log_append"]
+  PostToolUse:
+    matchers: [Bash, Edit, "mcp__coding-os__cos_backtrack_log", "mcp__coding-os__cos_task_move"]
+  Stop:
+    matchers: [""]
+  SubagentStart:
+    matchers: [""]
+  SubagentStop:
+    matchers: [""]
+  SessionStart:
+    matchers: [startup, "compact|resume", clear]
+  PreCompact:
+    matchers: [""]
+  PostCompact:
+    matchers: [""]
+  PermissionRequest:
+    matchers: [""]
+  UserPromptSubmit:
+    matchers: [""]
+  SessionEnd:
+    matchers: [""]
+
+# Codex launches multiple matching command hooks concurrently for the same
+# event. Coalesce selected groups into one dispatcher so sequencing and UI
+# visibility stay deterministic.
+hook_dispatchers:
+  - event: SessionEnd
+    matcher: ""
+    script: codex-sessionend-dispatch.sh
+    timeout: 3
+    delegates:
+      - agent-presence.sh
+  - event: PreToolUse
+    matcher: Bash
+    script: codex-pretool-dispatch.sh
+    delegates:
+      - block-secrets.sh
+      - block-dangerous-commands.sh
+      - branch-guard.sh
+      - enforce-commit-message.sh
+      - block-uv-heredoc.sh
+      - enforce-verify.sh
+      - test-governor.sh
+      - search-enforce-inventory.sh
+      - nudge-task-discovery.sh
+      - warn-diff-size.sh
+      - agent-presence.sh
+  - event: PreToolUse
+    matcher: Edit
+    script: codex-preedit-dispatch.sh
+    delegates:
+      - block-secrets.sh
+      - block-bad-patterns.sh
+      - block-protected-files.sh
+      - block-shared-tree-edit.sh
+      - enforce-task-transition.sh
+      - block-migration-conflict.sh
+      - block-hardcoded-literals.sh
+      - validate-task-frontmatter.sh
+      - enforce-wip-limit.sh
+      - enforce-template.sh
+      - thinking_os-gate.sh
+      - enforce-scaffold-boundary.sh
+      - enforce-task-start.sh
+      - enforce-doc-anchor.sh
+      - enforce-memory-check.sh
+      - enforce-skill.sh
+      - enforce-zoom.sh
+      - enforce-graph-context.sh
+      - warn-destructive-edit.sh
+      - enforce-rename-plan.sh
+      - enforce-task-body.sh
+      - enforce-anti-ambiguity.sh
+      - jit-recall.sh
+  - event: SessionStart
+    matcher: startup
+    script: codex-sessionstart-dispatch.sh
+    status_message: "🚀 Loading session context + MCP health..."
+    delegates:
+      - session-context.sh
+      - warn-mcp-down.sh
+      - check-mcp-extras.sh
+      - rules-primer.sh
+      - session-skill-primer.sh
+      - remind-daily.sh
+      - warn-graph-empty.sh
+      - auto-brain-decay.sh
+      - agent-presence.sh
+      - pr-reap.sh
+  - event: SessionStart
+    matcher: "compact|resume"
+    script: codex-sessionstart-dispatch.sh
+    status_message: "🔄 Recovering workflow context + MCP health..."
+    delegates:
+      - session-context.sh
+      - warn-mcp-down.sh
+      - check-mcp-extras.sh
+      - rules-primer.sh
+      - session-skill-primer.sh
+      - remind-daily.sh
+      - warn-graph-empty.sh
+      - auto-brain-decay.sh
+      - agent-presence.sh
+      - pr-reap.sh
+  - event: SessionStart
+    matcher: clear
+    script: codex-sessionstart-dispatch.sh
+    status_message: "Loading clean session context..."
+    delegates:
+      - session-context.sh
+      - warn-mcp-down.sh
+      - check-mcp-extras.sh
+      - rules-primer.sh
+      - session-skill-primer.sh
+      - remind-daily.sh
+      - warn-graph-empty.sh
+      - auto-brain-decay.sh
+      - agent-presence.sh
+      - pr-reap.sh
+  - event: Stop
+    matcher: ""
+    script: codex-stop-dispatch.sh
+    status_message: "📝 Finalizing session recap + memory enrichment..."
+    timeout: 5000
+    delegates:
+      - session-end.sh
+      - warn-abandoned-task.sh
+      - nudge-learn-narrative.sh
+      - check-capture-worked.sh
+      - auto-trace-rotate.sh
+      - snapshot-transcript.sh
+      - drain-embedding-outbox.sh
+      - agent-presence.sh
+  - event: PostToolUse
+    matcher: Bash
+    script: codex-posttool-dispatch.sh
+    delegates:
+      - remind-learn-validate.sh
+      - record-verify-auto.sh
+      - auto-graph-reconcile-shell.sh
+      - search-verify-remaining.sh
+      - advance-role.sh
+      - sync-task-current.sh
+      - agent-presence.sh
+  - event: PostToolUse
+    matcher: Edit
+    script: codex-postedit-dispatch.sh
+    delegates:
+      - lint-task.sh
+      - enforce-doc-sync.sh
+      - verify-rename-callers.sh
+      - advance-role.sh
+      - track-discovery.sh
+      - auto-reindex-docs.sh
+      - auto-regen-doc-index.sh
+      - auto-task-sync.sh
+      - capture-observation.sh
+      - capture-work-log.sh
+      - agent-presence.sh
+      - nudge-reuse-first.sh
+      - check-doc-size.sh
+      - regen-reminder.sh
+      - test-first-reminder.sh
+      - check-agents-md-size.sh
+      - check-agents-md-refs.sh
+      - remind-dogfood.sh
+  - event: UserPromptSubmit
+    matcher: ""
+    script: codex-userpromptsubmit-dispatch.sh
+    delegates:
+      - session-context.sh
+      - classify-task-mode.sh
+      - nudge-thinking-os.sh
+      - nudge-graph-os.sh
+      - nudge-model-routing.sh
+      - nudge-git-mode.sh
+      - nudge-reentry.sh
+      - nudge-task-discovery.sh
+      - nudge-docs-first.sh
+      - auto-compose-roles.sh
+      - agent-presence.sh

adapters/codex/chat_provider.py

@@ -0,0 +1,230 @@
+"""Codex Hub transcript provider backed by the official Python SDK."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar
+
+logger = logging.getLogger("coding_os.chat.codex")
+
+_CLIENT: Any = None
+_CLIENT_LOCK = asyncio.Lock()
+_T = TypeVar("_T")
+
+
+def available() -> bool:
+    try:
+        import openai_codex  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+async def _with_client(call: Callable[[Any], Awaitable[_T]]) -> _T:
+    global _CLIENT
+    async with _CLIENT_LOCK:
+        if _CLIENT is None:
+            from openai_codex import AsyncCodex
+
+            _CLIENT = AsyncCodex()
+        try:
+            return await call(_CLIENT)
+        except Exception:
+            try:
+                await _CLIENT.close()
+            except Exception as exc:
+                logger.debug("Codex chat client close failed: %s", exc)
+            _CLIENT = None
+            raise
+
+
+def _jsonable(value: Any) -> Any:
+    dump = getattr(value, "model_dump", None)
+    if callable(dump):
+        return dump(mode="json", by_alias=True)
+    root = getattr(value, "root", None)
+    if root is not None:
+        return _jsonable(root)
+    if hasattr(value, "value"):
+        return value.value
+    if isinstance(value, list):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): _jsonable(item) for key, item in value.items()}
+    return value
+
+
+def _session(thread: Any) -> dict[str, Any]:
+    git_info = getattr(thread, "git_info", None)
+    cwd = _jsonable(getattr(thread, "cwd", None))
+    return {
+        "session_id": thread.id,
+        "summary": None,
+        "custom_title": getattr(thread, "name", None),
+        "first_prompt": (getattr(thread, "preview", None) or "")[:400] or None,
+        "last_modified": int(getattr(thread, "updated_at", 0) or 0) * 1000 or None,
+        "file_size": None,
+        "git_branch": getattr(git_info, "branch", None),
+        "cwd": str(cwd) if cwd else None,
+        "tag": None,
+        "created_at": int(getattr(thread, "created_at", 0) or 0) * 1000 or None,
+        "agent": "codex",
+        "writable": False,
+        "source": _jsonable(getattr(thread, "source", None)),
+        "status": _jsonable(getattr(thread, "status", None)),
+        "model_provider": getattr(thread, "model_provider", None),
+    }
+
+
+def _message(
+    session_id: str,
+    item_id: str | None,
+    role: str,
+    blocks: list[dict[str, Any]],
+) -> dict[str, Any]:
+    return {
+        "uuid": item_id,
+        "session_id": session_id,
+        "type": role,
+        "role": role,
+        "model": None,
+        "stop_reason": None,
+        "usage": None,
+        "blocks": blocks,
+        "parent_tool_use_id": None,
+    }
+
+
+def _user_blocks(content: list[Any]) -> list[dict[str, Any]]:
+    blocks: list[dict[str, Any]] = []
+    for wrapped in content:
+        item = getattr(wrapped, "root", wrapped)
+        item_type = getattr(item, "type", "")
+        if item_type == "text":
+            blocks.append({"type": "text", "text": item.text})
+        elif item_type in {"image", "localImage"}:
+            target = getattr(item, "url", None) or getattr(item, "path", None) or "image"
+            blocks.append({"type": "text", "text": f"[image: {target}]"})
+        elif item_type in {"skill", "mention"}:
+            blocks.append({"type": "text", "text": f"${getattr(item, 'name', item_type)}"})
+    return blocks
+
+
+def _tool_messages(session_id: str, item: Any) -> list[dict[str, Any]]:
+    item_type = getattr(item, "type", "")
+    item_id = getattr(item, "id", None)
+    if item_type == "commandExecution":
+        name = "Bash"
+        arguments = {"command": getattr(item, "command", "")}
+        output = getattr(item, "aggregated_output", None)
+        failed = getattr(item, "exit_code", 0) not in (None, 0)
+    elif item_type == "mcpToolCall":
+        name = f"{getattr(item, 'server', 'mcp')}:{getattr(item, 'tool', 'tool')}"
+        arguments = _jsonable(getattr(item, "arguments", None))
+        output = _jsonable(getattr(item, "result", None) or getattr(item, "error", None))
+        failed = getattr(item, "error", None) is not None
+    elif item_type == "dynamicToolCall":
+        name = getattr(item, "tool", "tool")
+        arguments = _jsonable(getattr(item, "arguments", None))
+        output = _jsonable(getattr(item, "content_items", None))
+        failed = getattr(item, "success", None) is False
+    else:
+        return []
+    use_id = item_id or f"tool-{len(str(arguments))}"
+    return [
+        _message(
+            session_id,
+            item_id,
+            "assistant",
+            [{"type": "tool_use", "id": use_id, "name": name, "input": arguments}],
+        ),
+        _message(
+            session_id,
+            f"{use_id}-result",
+            "user",
+            [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": use_id,
+                    "content": "" if output is None else str(output),
+                    "is_error": failed,
+                }
+            ],
+        ),
+    ]
+
+
+def _messages(thread: Any) -> list[dict[str, Any]]:
+    messages: list[dict[str, Any]] = []
+    for turn in getattr(thread, "turns", []):
+        for wrapped in getattr(turn, "items", []):
+            item = getattr(wrapped, "root", wrapped)
+            item_type = getattr(item, "type", "")
+            item_id = getattr(item, "id", None)
+            if item_type == "userMessage":
+                blocks = _user_blocks(getattr(item, "content", []))
+                if blocks:
+                    messages.append(_message(thread.id, item_id, "user", blocks))
+            elif item_type == "agentMessage":
+                text = getattr(item, "text", "")
+                if text:
+                    messages.append(
+                        _message(thread.id, item_id, "assistant", [{"type": "text", "text": text}])
+                    )
+            elif item_type == "reasoning":
+                parts = getattr(item, "summary", None) or getattr(item, "content", None) or []
+                text = "\n\n".join(str(part) for part in parts if part)
+                if text:
+                    messages.append(
+                        _message(
+                            thread.id,
+                            item_id,
+                            "assistant",
+                            [{"type": "thinking", "text": text}],
+                        )
+                    )
+            else:
+                messages.extend(_tool_messages(thread.id, item))
+    return messages
+
+
+async def list_sessions(cwd: str, limit: int) -> list[dict[str, Any]]:
+    async def call(client: Any) -> Any:
+        return await client.thread_list(cwd=cwd, limit=limit, archived=False)
+
+    response = await _with_client(call)
+    return [_session(thread) for thread in response.data]
+
+
+async def get_session(
+    session_id: str,
+    cwd: str,
+    limit: int,
+    offset: int,
+) -> dict[str, Any] | None:
+    async def call(client: Any) -> Any:
+        from openai_codex import AsyncThread
+
+        return await AsyncThread(client, session_id).read(include_turns=True)
+
+    try:
+        response = await _with_client(call)
+    except Exception as exc:
+        message = str(exc).lower()
+        if "not found" in message or "no rollout found" in message:
+            return None
+        raise
+    thread = response.thread
+    if _jsonable(getattr(thread, "cwd", None)) != cwd:
+        return None
+    messages = _messages(thread)
+    page = messages[offset : offset + limit]
+    return {
+        "session": _session(thread),
+        "messages": page,
+        "count": len(page),
+        "offset": offset,
+        "meta": {"layer": "cognition", "source": "codex_sdk", "agent": "codex"},
+    }

adapters/codex/commands/formula-f1.md

@@ -0,0 +1,129 @@
+---
+id: researcher
+name: "Research & Discovery"
+formula_ref: researcher
+attach_phases: [MAP, CLASSIFY]
+canonical_order: 0
+intensity_min: light
+model_pref:
+  complicated: sonnet
+  complex: opus
+skills: [search, codebase-explorer]
+# Full-intensity research may need 1M context (large codebase/doc ingestion).
+# The Claude dispatcher passes betas=["context-1m-2025-08-07"] when set.
+long_context: true
+tools_budget:
+  - cos_search
+  - cos_doc_search
+  - cos_graph_query
+  - WebSearch
+  - WebFetch
+  - Glob
+  - Grep
+  - Read
+input_schema: cognition.ResearcherInput
+output_schema: cognition.ResearcherOutput
+max_tokens_in: 4000
+max_tokens_out: 2000
+timeout_s: 120
+intensity_steps:
+  light: [1, 2, 3]
+  standard: [1, 2, 3, 4, 5]
+  full: [1, 2, 3, 4, 5, 6]
+backtrack_triggers: []
+criteria_required:
+  step_1: [scoped, observable]
+  step_2: [observable, measurable]
+  step_3: [scoped, observable]
+  step_4: [observable, owned]
+  step_5: [scoped, observable]
+  step_6: [scoped, measurable, observable]
+---
+
+# researcher — Research & Discovery
+
+## Character
+I value grounding claims in sources because a confident guess costs more than an honest unknown. I cite what I find and I log what I cannot verify rather than inventing it. (no-guessing, SSOT-first)
+
+## Your role
+You are the researcher cognitive agent. Your job is to gather foundational knowledge
+before any analysis or architecture work begins. You reduce risk by surfacing
+what is known, what is contested, and what is unknown about the problem domain.
+
+## Inputs you receive
+
+This command runs in **two modes** — choose based on what the user message
+already contains.
+
+**(A) Composer mode** — `cos_dispatch_formula_run` invoked this role. The user
+message contains a `ResearcherInput` JSON object (shape defined by the
+`input_schema` frontmatter field).
+
+**(B) Interactive mode** — user invoked the slash command and the user
+message has **no `ResearcherInput`-shaped JSON**. Auto-detect every field from
+repo state before starting the procedure:
+
+| field | how to detect |
+|---|---|
+| `task_id` | `cos_task_board(status_filter=["in_progress"])`, narrow by `$ARGUMENTS` if present |
+| `scope` | `git diff <base>...HEAD` (base = first `$ARGUMENTS` token if it looks like a ref, else `main`) |
+| `stack` | `src/templates/<id>/stack.yaml` of the enabled template |
+| `domain` | `cos_doc_headers_by(domain=...)` or the active task's frontmatter |
+| `nfr_targets` | `docs/_meta/nfr.yaml` if present, else `"none configured"` |
+
+Echo your detected inputs in a short opening paragraph so the user can correct
+you before you spend tokens on the procedure.
+
+
+## Procedure
+
+**Step 1 — Domain landscape**
+Search internal memory (`cos_search`) and docs (`cos_doc_search`) for prior
+work on this domain. Note what patterns already exist in this codebase.
+
+**Step 2 — External signals** (standard+full only)
+If `domain` is non-empty, search external sources for recent developments,
+known pitfalls, and established solutions. Focus on the last 12 months.
+
+**Step 3 — Competing approaches**
+Identify 2–4 alternative approaches to the problem. List trade-offs.
+Do NOT commit to a recommendation yet — that is architect's job.
+
+**Step 4 — Constraint surfacing** (standard+full)
+List known constraints: compliance, team skill, existing infra, timeline.
+Each constraint must name an owner (`owned` criterion).
+
+**Step 5 — Open questions** (standard+full)
+List questions that analyst or architect must answer before design proceeds.
+
+**Step 6 — Recommendations summary** (full only)
+State which approach is most likely to succeed given constraints,
+with measurable success criteria.
+
+## Output contract
+
+**Match the invocation mode**:
+
+**(A) Composer mode** — return JSON only matching `ResearcherOutput`. No prose
+outside the fenced block:
+
+```json
+{
+  "summary": "...",
+  "sources": [{"title": "...", "url_or_path": "...", "relevance": "..."}],
+  "key_findings": ["..."],
+  "open_questions": ["..."],
+  "recommended_next": "..."
+}
+```
+**(B) Interactive mode** — return a Markdown review with these sections:
+
+1. **Detected inputs** — one paragraph echoing task_id / scope / stack / nfr.
+2. **Summary** — one paragraph: what was done, overall verdict.
+3. **Findings or Deliverables** — bulleted; severities critical / high / medium / low / info where applicable.
+4. **Next step** — single recommended action (or "ready to hand off to <next-role>").
+
+Then append the **same `ResearcherOutput` envelope** as a fenced ```json``` block
+at the very bottom so `cos_supervise_record_output` can parse it. Both
+audiences (human + composer) consume the same output from one emission.
+