codeer-cli 0.1.9__tar.gz → 0.1.11__tar.gz

{codeer_cli-0.1.9 → codeer_cli-0.1.11}/API_REFERENCE.md

@@ -3,8 +3,9 @@
 > This file is the request-shape reference for maintaining `codeer-cli`.
 
 The 9 stages below mirror the user-docs lifecycle (`agent-creation` →
-`optimization-loop` → `publish`). Every path is under `/api/v1/`. All endpoints
-authenticate via `x-api-key` from `CODEER_API_KEY`.
+`optimization-loop` → `publish`). Agent, KB, eval, history, and model paths are
+under `/api/v1/`; Chat create/message/read paths use `/api/v2/chats`. All
+endpoints authenticate via `x-api-key` from `CODEER_API_KEY`.
 
 Envelope: successful responses look like
 `{"error_code": 0, "message": "", "pagination": null, "data": <payload>}`.
@@ -49,6 +50,23 @@ like `knowledge_node_ids`, `domain`, `agent_id`, `http_request` config.
 
 Limits: 10 tools per agent, ≤5 `call_agent`, ≤1 `memory`.
 
+Agent create/update payloads may also include:
+
+```json
+{
+  "human_handoff": {
+    "enabled": true,
+    "idle_timeout_minutes": null,
+    "handoff_instructions": "Hand off when the user asks for a person."
+  }
+}
+```
+
+`idle_timeout_minutes` must be greater than zero when provided. The runtime
+only exposes the handoff tool to an external conversation with a non-empty
+`external_user_id`, or to an evaluation run. Internal editor Live Test does not
+activate human mode.
+
 ## Stage 2 — Knowledge bases
 
 Base path: `/organizations/{org_id}/workspaces/{ws_id}/knowledge_bases`
@@ -123,19 +141,21 @@ codeer kb files --kb-id <kb-id>
 codeer kb faq-create --context-object-id <snapshot-object-id> --question "..." --range 12:0-12:42 --dry-run
 ```
 
-## Stage 3 — Live Test on a specific version
+## Stage 3 — Live Test on a specific version (legacy V1 compatibility)
 
 | Method & path | Purpose |
 | --- | --- |
-| `POST /chats` | Create a new chat session bound to an agent |
-| `POST /chats/{chat_id}/messages` | Send a message; **SSE stream** of tool calls + reasoning + final text |
-| `GET /chats/{chat_id}/messages` | Read historical messages for a chat |
-| `POST /chats/{chat_id}/regenerate` | Re-run the last turn |
-| `POST /chats/{chat_id}/messages/{msg_id}/feedbacks` | Thumbs up/down on a reply |
-
-`POST /chats/.../messages` requires `agent_history_id` — this is the key hook
-for the apply → test → publish workflow. Pass the draft `AgentHistory.id` from
-`PUT /agents/{id}` to test an unpublished version.
+| `POST /api/v1/chats` | Create a legacy chat session bound to an agent |
+| `POST /api/v1/chats/{chat_id}/messages` | Send a version-pinned message through legacy SSE |
+| `GET /api/v1/chats/{chat_id}/messages` | Read legacy messages for a chat |
+| `POST /api/v1/chats/{chat_id}/regenerate` | Re-run the last turn |
+| `POST /api/v1/chats/{chat_id}/messages/{msg_id}/feedbacks` | Thumbs up/down on a reply |
+
+Legacy V1 `POST /chats/.../messages` accepts `agent_history_id` — this is the
+compatibility hook for the apply → test → publish workflow. Pass the draft
+`AgentHistory.id` from `PUT /agents/{id}` to test an unpublished version.
+The API-key external flow in Chat V2 accepts `agent_id` and runs its published
+version; it does not currently replace this draft-pinning path.
 
 ## Stage 4 — Version management
 
@@ -250,8 +270,9 @@ the public CLI.
 
 | Method & path | Purpose |
 | --- | --- |
-| `POST /chats` | Create a persisted history using an agent's current published version |
-| `POST /chats/{id}/messages` | Append a turn to an existing persisted history using the current published version |
+| `POST /api/v2/chats` | Create a persisted history using an agent's current published version |
+| `POST /api/v2/chats/{id}/messages` | Append a turn through structured SSE using the current published version |
+| `GET /api/v2/chats/{id}/messages` | Read persisted Chat V2 conversation parts |
 | `GET /histories?agent_id=X&feedback_filter=improve_feedback&external_user_id=…` | List conversations with filters |
 | `GET /histories/{id}` | Read one history's metadata |
 | `GET /histories/{id}/conversations` | Full conversation turns incl. tool calls |
@@ -259,9 +280,11 @@ the public CLI.
 | `POST /histories/{hid}/conversations/{cid}/score` | Numeric score |
 
 The CLI exposes the first two operations as `codeer history create` and
-`codeer history send`. Non-streaming message requests default to a 120-second
-per-message timeout. A timeout has an uncertain write outcome, so read the
-history before retrying to avoid duplicate turns.
+`codeer history send`. Messages explicitly set `stream: true`, consume Chat V2
+SSE, and require `response.completed` before reporting success. Their
+per-message SSE read timeout defaults to 240 seconds. A timeout,
+`response.failed`, or disconnect before completion has an uncertain write
+outcome, so read the history before retrying to avoid duplicate turns.
 
 `feedback_filter` accepts the `FeedbackFilterType` enum values:
 `no_feedback`, `with_feedback`, `helpful_feedback`, `improve_feedback`.
@@ -280,7 +303,7 @@ Non-destructive: older versions stay in `GET /agents/{id}/histories`.
 | --- | --- |
 | `GET /accounts/me` | Sanity-check session, read workspace_organization_map |
 | `GET /organizations` | List orgs visible to the user |
-| `GET /llm/models` | List available LLM model IDs to use as `llm_model` |
+| `GET /llm/models` | List available LLM model IDs to use as `llm_model` (`codeer model list`) |
 | `GET /retrieval/...` | Shared retrieval helpers (file upload for attachments, markdown conversion) |
 
 ---
@@ -340,7 +363,7 @@ said (scope, factuality, tool-use rules).
 
 ### 4. Agent version pinning works everywhere — use it
 
-Both `POST /chats/{id}/messages` (`agent_history_id` required) and
+Legacy V1 `POST /chats/{id}/messages` (`agent_history_id` required) and
 `POST /eval/trigger` (`agent_history_id` optional, null = live state) accept
 the draft history id. The apply-→-test-→-publish loop:
 
@@ -446,9 +469,10 @@ pass. Workspace scope is inferred from the API-key virtual user profile.
 
 ### 11. Tool args + outputs are NOT persisted in history reads
 
-Conversations have only three roles (`OpenAIChatRole = system | user | assistant`)
-— there is no `tool` role row. When you read a history, here's what you can
-and can't recover from each assistant turn:
+Legacy V1 `History` conversation rows have only three roles
+(`OpenAIChatRole = system | user | assistant`) — there is no `tool` role row.
+When you read those rows through `/histories/{id}/conversations`, here's what
+you can and can't recover from each assistant turn:
 
 | Recoverable | Where |
 | --- | --- |
@@ -464,10 +488,12 @@ and can't recover from each assistant turn:
 | Tool **outputs** (raw JSON returned by the tool) | same — stored only as derived `primary_sources` for retrieval tools |
 | Reasoning steps mid-turn | `meta.reasoning_steps` is currently always `null` |
 
-If you need full tool I/O, capture it at execution time via the chat SSE
-stream (`POST /chats/{id}/messages`), not from history reads. For after-the-
-fact analysis, the persisted shape is sufficient to surface tool-selection
-patterns, token costs, and which sources the agent ended up citing.
+Chat V2 improves this contract: structured SSE emits tool calls and returns as
+`response.part.created` / `response.part.completed`, and
+`GET /api/v2/chats/{id}/messages` reads the persisted conversation parts.
+Capture the SSE artifact with `--out` when exact event order matters; use the
+V2 message read for persisted after-the-fact tool I/O. The legacy v1 history
+read remains useful for compact turn-level analysis.
 
 ### 10. A KB has exactly ONE level of folders — no nesting
 

{codeer_cli-0.1.9 → codeer_cli-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeer-cli
-Version: 0.1.9
+Version: 0.1.11
 Summary: Command line tools for managing Codeer agents over the Codeer API.
 Project-URL: Homepage, https://www.codeer.ai
 Author: Codeer.AI
@@ -117,6 +117,35 @@ Validate setup before API work:
 codeer check
 ```
 
+List the active cloud models without opening the Codeer web app:
+
+```bash
+codeer model list --type text
+```
+
+## Agent human handoff
+
+`codeer agent apply` accepts the same `human_handoff` object as the Agent API.
+The dry-run validates it and shows whether handoff is enabled before any server
+write:
+
+```json
+{
+  "name": "Support Agent",
+  "system_prompt": "Help the user safely.",
+  "human_handoff": {
+    "enabled": true,
+    "idle_timeout_minutes": null,
+    "handoff_instructions": "Hand off when the user asks for a person."
+  }
+}
+```
+
+`idle_timeout_minutes` must be a positive integer or `null`. Human handoff only
+becomes available in live published-agent conversations with a non-empty
+`external_user_id`; editor Live Test conversations are internal and cannot
+activate human mode.
+
 ## Upgrade and uninstall
 
 Upgrade the CLI:
@@ -143,15 +172,17 @@ Use this pattern during agent lifecycle work:
 ```bash
 codeer agent list
 codeer history list --agent <agent-id> --limit 50
-codeer history create --agent <agent-id> --message "Review this plan" --timeout 120
-codeer history send <history-id> --message "Use the recommended options" --timeout 120
+codeer history create --agent <agent-id> --message "Review this plan" --timeout 240
+codeer history send <history-id> --message "Use the recommended options" --timeout 240
 codeer eval run --agent <agent-id> --cases <case-ids> --evaluator <evaluator-id> --out .codeer/eval_run.json
 ```
 
 `history create` and `history send` use the agent's current published version.
-Their per-message timeout defaults to 120 seconds. If a write request times
-out, inspect the history before retrying: the server may have completed the
-turn after the client stopped waiting.
+They use Chat V2 structured SSE with `stream: true`; their per-message read
+timeout defaults to 240 seconds. Success requires a `response.completed`
+event. If the stream times out, reports `response.failed`, or disconnects
+early, inspect the history before retrying: the server may already have
+persisted the turn.
 
 Eval case label commands always operate on the active API-key workspace. They
 do not accept a workspace override; switch CLI profiles to target another

{codeer_cli-0.1.9 → codeer_cli-0.1.11}/README.md

@@ -99,6 +99,35 @@ Validate setup before API work:
 codeer check
 ```
 
+List the active cloud models without opening the Codeer web app:
+
+```bash
+codeer model list --type text
+```
+
+## Agent human handoff
+
+`codeer agent apply` accepts the same `human_handoff` object as the Agent API.
+The dry-run validates it and shows whether handoff is enabled before any server
+write:
+
+```json
+{
+  "name": "Support Agent",
+  "system_prompt": "Help the user safely.",
+  "human_handoff": {
+    "enabled": true,
+    "idle_timeout_minutes": null,
+    "handoff_instructions": "Hand off when the user asks for a person."
+  }
+}
+```
+
+`idle_timeout_minutes` must be a positive integer or `null`. Human handoff only
+becomes available in live published-agent conversations with a non-empty
+`external_user_id`; editor Live Test conversations are internal and cannot
+activate human mode.
+
 ## Upgrade and uninstall
 
 Upgrade the CLI:
@@ -125,15 +154,17 @@ Use this pattern during agent lifecycle work:
 ```bash
 codeer agent list
 codeer history list --agent <agent-id> --limit 50
-codeer history create --agent <agent-id> --message "Review this plan" --timeout 120
-codeer history send <history-id> --message "Use the recommended options" --timeout 120
+codeer history create --agent <agent-id> --message "Review this plan" --timeout 240
+codeer history send <history-id> --message "Use the recommended options" --timeout 240
 codeer eval run --agent <agent-id> --cases <case-ids> --evaluator <evaluator-id> --out .codeer/eval_run.json
 ```
 
 `history create` and `history send` use the agent's current published version.
-Their per-message timeout defaults to 120 seconds. If a write request times
-out, inspect the history before retrying: the server may have completed the
-turn after the client stopped waiting.
+They use Chat V2 structured SSE with `stream: true`; their per-message read
+timeout defaults to 240 seconds. Success requires a `response.completed`
+event. If the stream times out, reports `response.failed`, or disconnects
+early, inspect the history before retrying: the server may already have
+persisted the turn.
 
 Eval case label commands always operate on the active API-key workspace. They
 do not accept a workspace override; switch CLI profiles to target another

{codeer_cli-0.1.9 → codeer_cli-0.1.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codeer-cli"
-version = "0.1.9"
+version = "0.1.11"
 description = "Command line tools for managing Codeer agents over the Codeer API."
 readme = "README.md"
 requires-python = ">=3.11"

{codeer_cli-0.1.9 → codeer_cli-0.1.11}/src/codeer_cli/__init__.py

@@ -18,7 +18,7 @@ production and can be overridden from process env. The CLI does not read
 workspace-local dotenv files or credential files.
 """
 
-from ._validate import ToolValidationError
+from ._validate import HumanHandoffValidationError, ToolValidationError
 from .client import AuthError, CodeerClient, CodeerError, TransportError
 from .parse import (
     AgentSummary,
@@ -44,6 +44,7 @@ from .parse import (
 
 __all__ = [
     "CodeerClient", "CodeerError", "TransportError", "AuthError", "ToolValidationError",
+    "HumanHandoffValidationError",
     # parsers
     "AgentSummary", "ConversationTurn", "EvalResultSummary", "HistorySummary",
     "KBNode", "ToolCall", "EvalToolCall",

{codeer_cli-0.1.9 → codeer_cli-0.1.11}/src/codeer_cli/_validate.py

@@ -1,4 +1,4 @@
-"""Client-side validation for unified-tool payloads.
+"""Client-side validation for agent payloads.
 
 These checks exist because the backend's form-schema validator is lenient
 (``extra="allow"``) and silently accepts unknown ``type`` strings, which then
@@ -24,6 +24,47 @@ class ToolValidationError(ValueError):
     """Raised when a unified_tools payload is definitely wrong."""
 
 
+class HumanHandoffValidationError(ValueError):
+    """Raised when a human_handoff payload is definitely wrong."""
+
+
+def validate_human_handoff(config: Any) -> dict[str, Any] | None:
+    """Validate and normalize an optional human-handoff configuration."""
+    if config is None:
+        return None
+    if not isinstance(config, dict):
+        raise HumanHandoffValidationError("human_handoff must be an object.")
+
+    allowed_keys = {"enabled", "idle_timeout_minutes", "handoff_instructions"}
+    unknown_keys = sorted(set(config) - allowed_keys)
+    if unknown_keys:
+        raise HumanHandoffValidationError(
+            f"human_handoff contains unsupported field(s): {', '.join(unknown_keys)}."
+        )
+
+    enabled = config.get("enabled", False)
+    if not isinstance(enabled, bool):
+        raise HumanHandoffValidationError("human_handoff.enabled must be true or false.")
+
+    timeout = config.get("idle_timeout_minutes")
+    if timeout is not None and (type(timeout) is not int or timeout <= 0):
+        raise HumanHandoffValidationError(
+            "human_handoff.idle_timeout_minutes must be a positive integer or null."
+        )
+
+    instructions = config.get("handoff_instructions")
+    if instructions is not None and not isinstance(instructions, str):
+        raise HumanHandoffValidationError(
+            "human_handoff.handoff_instructions must be a string or null."
+        )
+
+    return {
+        "enabled": enabled,
+        "idle_timeout_minutes": timeout,
+        "handoff_instructions": instructions,
+    }
+
+
 def validate_unified_tools(tools: Iterable[dict[str, Any]] | None) -> list[dict[str, Any]]:
     """Raise ToolValidationError on invalid payloads; otherwise return the list.
 

{codeer_cli-0.1.9 → codeer_cli-0.1.11}/src/codeer_cli/agents.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 
 from typing import Any, List, Optional
 
-from ._validate import validate_unified_tools
+from ._validate import validate_human_handoff, validate_unified_tools
 from .client import CodeerClient
 
 
@@ -24,8 +24,10 @@ def create(
     suggested_questions: Optional[List[str]] = None,
     primary_object_ids: Optional[List[int]] = None,
     attachment_ids: Optional[List[str]] = None,
+    human_handoff: Optional[dict[str, Any]] = None,
 ) -> dict:
     validated_tools = validate_unified_tools(unified_tools)
+    validated_handoff = validate_human_handoff(human_handoff)
     body: dict[str, Any] = {
         "name": name,
         "system_prompt": system_prompt,
@@ -39,6 +41,8 @@ def create(
         body["description"] = description
     if llm_model is not None:
         body["llm_model"] = llm_model
+    if validated_handoff is not None:
+        body["human_handoff"] = validated_handoff
     return client.post("/external/agents", json=body)
 
 
@@ -56,9 +60,11 @@ def update(
     suggested_questions: Optional[List[str]] = None,
     primary_object_ids: Optional[List[int]] = None,
     attachment_ids: Optional[List[str]] = None,
+    human_handoff: Optional[dict[str, Any]] = None,
 ) -> dict:
     """PUT creates a new AgentHistory snapshot (draft)."""
     validated_tools = validate_unified_tools(unified_tools)
+    validated_handoff = validate_human_handoff(human_handoff)
     body: dict[str, Any] = {
         "name": name,
         "system_prompt": system_prompt,
@@ -73,6 +79,8 @@ def update(
         body["description"] = description
     if llm_model is not None:
         body["llm_model"] = llm_model
+    if validated_handoff is not None:
+        body["human_handoff"] = validated_handoff
     return client.patch(f"/external/agents/{agent_id}", json=body)
 
 

codeer_cli-0.1.11/src/codeer_cli/chats.py

@@ -0,0 +1,201 @@
+"""Chat V2 creation, structured SSE responses, and persisted message reads."""
+
+from __future__ import annotations
+
+from typing import Any, Iterator, List, Optional
+
+from .client import CodeerClient, TransportError
+
+
+def create(
+    client: CodeerClient,
+    *,
+    agent_id: str,
+    title: Optional[str] = None,
+    external_user_id: Optional[str] = None,
+) -> dict:
+    body: dict[str, Any] = {
+        "agent_id": agent_id,
+        "name": title or "CLI conversation",
+    }
+    if external_user_id is not None:
+        body["external_user_id"] = external_user_id
+    return client.post("/chats", api_version="v2", json=body)
+
+
+def send_published_agent_message(
+    client: CodeerClient,
+    *,
+    chat_id: int,
+    message: str,
+    agent_id: str,
+    external_user_id: Optional[str] = None,
+    attachment_ids: Optional[List[str]] = None,
+    stream: bool = True,
+    timeout: Optional[float] = None,
+) -> Iterator[dict] | dict:
+    """Send a user message through the API-key external chat flow.
+
+    API-key chat endpoints use the agent's published version. They accept
+    ``agent_id`` rather than ``agent_history_id``.
+    """
+    body: dict[str, Any] = {"message": message, "agent_id": agent_id, "stream": stream}
+    if external_user_id is not None:
+        body["external_user_id"] = external_user_id
+    if attachment_ids:
+        body["attached_file_uuids"] = attachment_ids
+
+    path = f"/chats/{chat_id}/messages"
+    if stream:
+        return client.stream_sse(
+            "POST",
+            path,
+            api_version="v2",
+            json=body,
+            timeout=timeout,
+        )
+    return client.post(path, api_version="v2", json=body, timeout=timeout)
+
+
+def send_message(
+    client: CodeerClient,
+    *,
+    chat_id: int,
+    message: str,
+    agent_history_id: str,
+    attachment_ids: Optional[List[str]] = None,
+    stream: bool = True,
+    timeout: Optional[float] = None,
+) -> Iterator[dict] | dict:
+    """Use legacy Chat V1 to pin an unpublished agent version.
+
+    Chat V2's API-key external flow only accepts the published ``agent_id``.
+    Keep this low-level compatibility helper on V1 until V2 supports external
+    ``agent_history_id`` pinning. It remains streaming by default.
+    """
+    body: dict[str, Any] = {
+        "message": message,
+        "agent_history_id": agent_history_id,
+        "stream": stream,
+    }
+    if attachment_ids:
+        body["attachment_ids"] = attachment_ids
+
+    path = f"/chats/{chat_id}/messages"
+    if stream:
+        return client.stream_sse(
+            "POST",
+            path,
+            json=body,
+            timeout=timeout,
+        )
+    return client.post(path, json=body, timeout=timeout)
+
+
+def collect_stream(events: Iterator[dict]) -> dict:
+    """Collect a Chat V2 SSE stream and require an explicit completion event."""
+    raw_events: list[dict] = []
+    parts: list[dict] = []
+    interactions: list[dict] = []
+    text_deltas: list[str] = []
+    final_text: str | None = None
+    response_id: str | None = None
+    conversation_group_id: str | None = None
+    updated_title: str | None = None
+    completed = False
+
+    for event in events:
+        data = event.get("data")
+        if data == "[DONE]":
+            continue
+        raw_events.append(event)
+        if not isinstance(data, dict):
+            continue
+
+        event_type = str(data.get("type") or event.get("event") or "message")
+        response_id = str(data.get("response_id") or response_id or "") or None
+        conversation_group_id = str(
+            data.get("conversation_group_id") or conversation_group_id or ""
+        ) or None
+
+        if event_type == "response.part.delta":
+            delta = data.get("delta")
+            if data.get("part_kind") == "text" and isinstance(delta, str):
+                text_deltas.append(delta)
+        elif event_type in ("response.part.created", "response.part.completed"):
+            part = data.get("part")
+            if isinstance(part, dict):
+                parts.append({"event": event_type, "part": part})
+                content = part.get("content")
+                if (
+                    event_type == "response.part.completed"
+                    and part.get("part_kind") == "text"
+                    and isinstance(content, dict)
+                    and isinstance(content.get("content"), str)
+                ):
+                    final_text = content["content"]
+        elif event_type in ("response.interaction.created", "response.interaction.resolved"):
+            interactions.append(data)
+        elif event_type == "response.chat.title.updated":
+            name = data.get("name")
+            if isinstance(name, str):
+                updated_title = name
+        elif event_type == "response.failed":
+            message = data.get("message") or "Chat V2 stream failed"
+            raise TransportError(
+                str(message),
+                {
+                    "code": data.get("code"),
+                    "response_id": response_id,
+                    "conversation_group_id": conversation_group_id,
+                    "outcome_uncertain": True,
+                    "events": raw_events,
+                },
+            )
+        elif event_type == "response.completed":
+            completed = True
+
+    if not completed:
+        raise TransportError(
+            "Chat V2 stream ended before response.completed. Inspect the history before retrying.",
+            {
+                "response_id": response_id,
+                "conversation_group_id": conversation_group_id,
+                "outcome_uncertain": True,
+                "events": raw_events,
+            },
+        )
+
+    return {
+        "stream": True,
+        "completed": True,
+        "response_id": response_id,
+        "conversation_group_id": conversation_group_id,
+        "final_text": final_text if final_text is not None else "".join(text_deltas),
+        "updated_title": updated_title,
+        "parts": parts,
+        "interactions": interactions,
+        "events": raw_events,
+    }
+
+
+def list_messages(
+    client: CodeerClient,
+    chat_id: int,
+    *,
+    external_user_id: Optional[str] = None,
+    limit: int = 500,
+) -> dict:
+    params: dict[str, Any] = {"limit": limit, "offset": 0}
+    if external_user_id is not None:
+        params["external_user_id"] = external_user_id
+    return client.get(
+        f"/chats/{chat_id}/messages",
+        api_version="v2",
+        params=params,
+    )
+
+
+def list_chats(client: CodeerClient) -> list[dict]:
+    """List chats through the legacy v1 endpoint; Chat V2 has no list route."""
+    return client.get("/chats")

{codeer_cli-0.1.9 → codeer_cli-0.1.11}/src/codeer_cli/cli.py

@@ -2,6 +2,7 @@
 
     codeer check
     codeer agent list|get|apply|diff|versions
+    codeer model list
     codeer kb list|files|upload|node-rename|node-delete|faq-list|faq-get|faq-create|faq-update|faq-delete
     codeer eval list|label-list|label-create|label-update|label-delete|case-update|case-delete|evaluators|evaluator-create|evaluator-update|run|export|reconcile|cases-apply|rubrics|rubrics-apply
     codeer history list|get|conversations|negative-feedback|create|send
@@ -25,6 +26,7 @@ def main(argv: list[str] | None = None) -> int:
         epilog="""\
 Safe workflow for coding agents:
   codeer check --json
+  codeer model list --type text
   codeer agent list
   codeer agent get <agent-id> --full
   codeer kb list
@@ -55,6 +57,12 @@ Use --out <path> for large raw artifacts; stdout defaults to compact summaries.
 
     check.register(sub)
 
+    try:
+        from .commands import model as model_cmd
+        model_cmd.register(sub)
+    except ImportError:
+        pass
+
     # Phase 2-4: agent, kb, eval commands will register here
     try:
         from .commands import agent as agent_cmd