codeer-cli 0.1.9__py3-none-any.whl → 0.1.10__py3-none-any.whl

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/_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/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/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

codeer_cli/commands/agent.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Optional
 
 from .. import agents as agents_mod
+from .._validate import validate_human_handoff, validate_unified_tools
 from ..client import CodeerClient
 from ._util import log, print_json, strip_noisy_fields, truncate, write_json
 
@@ -102,6 +103,12 @@ def _tool_summary(tools: list[dict] | None) -> list[dict]:
 
 def _agent_summary(agent: dict, *, full: bool = False) -> dict:
     tools = agent.get("unified_tools") or agent.get("tools") or []
+    human_handoff = agent.get("human_handoff")
+    if not isinstance(human_handoff, dict):
+        meta = agent.get("meta")
+        human_handoff = meta.get("human_handoff") if isinstance(meta, dict) else {}
+    if not isinstance(human_handoff, dict):
+        human_handoff = {}
     row = {
         "id": agent.get("id"),
         "name": agent.get("name"),
@@ -118,6 +125,7 @@ def _agent_summary(agent: dict, *, full: bool = False) -> dict:
         "agent_type": agent.get("agent_type"),
         "updated_at": agent.get("updated_at"),
         "tool_count": len(tools),
+        "human_handoff_enabled": bool(human_handoff.get("enabled")),
         "system_prompt_chars": len(agent.get("system_prompt") or ""),
     }
     if full:
@@ -125,6 +133,7 @@ def _agent_summary(agent: dict, *, full: bool = False) -> dict:
         row["use_search"] = agent.get("use_search")
         row["suggested_questions"] = agent.get("suggested_questions") or []
         row["tools"] = _tool_summary(tools)
+        row["human_handoff"] = human_handoff
         row["system_prompt_preview"] = truncate(agent.get("system_prompt") or "", 1200)
     return row
 
@@ -153,6 +162,13 @@ def run_apply(args, client) -> int:
         log(f"error: payload missing required field(s): {', '.join(missing)}")
         return 2
 
+    try:
+        validated_tools = validate_unified_tools(body.get("unified_tools") or [])
+        validated_handoff = validate_human_handoff(body.get("human_handoff"))
+    except ValueError as exc:
+        log(f"error: invalid agent payload: {exc}")
+        return 2
+
     if args.dry_run:
         operation = "update" if args.agent_id else "create"
         result = {
@@ -162,9 +178,14 @@ def run_apply(args, client) -> int:
             "payload": str(Path(args.payload)),
             "name": body.get("name"),
             "system_prompt_chars": len(body.get("system_prompt") or ""),
-            "tool_count": len(body.get("unified_tools") or []),
+            "tool_count": len(validated_tools),
             "use_search": body.get("use_search", False),
             "llm_model": body.get("llm_model"),
+            "human_handoff": {
+                "enabled": bool((validated_handoff or {}).get("enabled")),
+                "idle_timeout_minutes": (validated_handoff or {}).get("idle_timeout_minutes"),
+                "instructions_chars": len((validated_handoff or {}).get("handoff_instructions") or ""),
+            },
             "version_note": args.note if args.agent_id else None,
             "would_write_server_state": True,
             "next_step": "Review this summary, then rerun without --dry-run after approval.",
@@ -178,7 +199,7 @@ def run_apply(args, client) -> int:
             client, args.agent_id,
             name=body["name"],
             system_prompt=body["system_prompt"],
-            unified_tools=body.get("unified_tools") or [],
+            unified_tools=validated_tools,
             use_search=body.get("use_search", False),
             version_note=args.note,
             description=body.get("description"),
@@ -186,6 +207,7 @@ def run_apply(args, client) -> int:
             suggested_questions=body.get("suggested_questions") or [],
             primary_object_ids=body.get("primary_object_ids") or [],
             attachment_ids=body.get("attachment_ids") or [],
+            human_handoff=validated_handoff,
         )
         agent_id = args.agent_id
         log(f"PUT /agents/{agent_id} ok")
@@ -197,13 +219,14 @@ def run_apply(args, client) -> int:
             workspace_id=body["workspace_id"],
             name=body["name"],
             system_prompt=body["system_prompt"],
-            unified_tools=body.get("unified_tools") or [],
+            unified_tools=validated_tools,
             use_search=body.get("use_search", False),
             description=body.get("description"),
             llm_model=body.get("llm_model"),
             suggested_questions=body.get("suggested_questions") or [],
             primary_object_ids=body.get("primary_object_ids") or [],
             attachment_ids=body.get("attachment_ids") or [],
+            human_handoff=validated_handoff,
         )
         agent_id = agent["id"]
         log(f"POST /agents ok, id={agent_id}")

codeer_cli/commands/model.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from .. import models as models_mod
+from ._util import print_json, strip_noisy_fields, write_json
+
+
+def register(subparsers):
+    model = subparsers.add_parser("model", help="Available LLM models")
+    sub = model.add_subparsers(dest="action", required=True)
+
+    p = sub.add_parser("list", help="List active cloud LLM models available to agents")
+    p.add_argument("--type", choices=("text", "image"), default=None,
+                   help="Filter by model type")
+    p.add_argument("--full", action="store_true",
+                   help="Include modalities, pricing, and creation metadata")
+    p.add_argument("--out", default=None,
+                   help="Write the complete model response to this file")
+    p.set_defaults(func=run_list)
+
+
+def _model_summary(model: dict, *, full: bool = False) -> dict:
+    row = {
+        "display_name": model.get("display_name"),
+        "model_id": model.get("model_id"),
+        "provider": model.get("provider"),
+        "model_type": model.get("model_type"),
+    }
+    if full:
+        row.update({
+            "input_modalities": model.get("input_modalities") or [],
+            "input_credits_per_million_tokens": model.get("input_credits_per_million_tokens"),
+            "output_credits_per_million_tokens": model.get("output_credits_per_million_tokens"),
+            "created_at": model.get("created_at"),
+        })
+    return row
+
+
+def run_list(args, client) -> int:
+    result = models_mod.list_available(client, model_type=args.type)
+    full_result = strip_noisy_fields(result)
+    write_json(args.out, full_result)
+    print_json([_model_summary(model, full=args.full) for model in result])
+    return 0

codeer_cli/models.py

@@ -0,0 +1,16 @@
+"""Available LLM model discovery."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .client import CodeerClient
+
+
+def list_available(
+    client: CodeerClient,
+    *,
+    model_type: Optional[str] = None,
+) -> list[dict]:
+    params = {"model_type": model_type} if model_type else None
+    return client.get("/llm/models", params=params)

{codeer_cli-0.1.9.dist-info → codeer_cli-0.1.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeer-cli
-Version: 0.1.9
+Version: 0.1.10
 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:

{codeer_cli-0.1.9.dist-info → codeer_cli-0.1.10.dist-info}/RECORD

@@ -1,23 +1,25 @@
-codeer_cli/__init__.py,sha256=slzDQ-Le6vl5PrimV6ZKmcDcNsQ7my7yG-Is1JVlbi4,1851
-codeer_cli/_validate.py,sha256=pKUJa2TyTpERx5xmiYNZRn7tFqDxLZ2fF1rHAf1oz14,5415
-codeer_cli/agents.py,sha256=diodgiGhXlowEi8sbCzcSK1qSeCLF2fBe6QBs3Sq_x8,5617
+codeer_cli/__init__.py,sha256=z3rkUdVCt11c8QE3-YFkG5cFObM6QhPe2yKugA8k3aA,1915
+codeer_cli/_validate.py,sha256=lqMwkhsBy1g0o5CINBp1HdBCjMawgUaEsZygjJaAPL0,6943
+codeer_cli/agents.py,sha256=HWfz6QgU4wn07df5s3twxVJfAhb0vLJHIfxTjvDMUzU,6045
 codeer_cli/chats.py,sha256=pww_AVByTh_AT2Td0gj2OomJrcw7D-cjDIpQ0ZQOlrM,2728
-codeer_cli/cli.py,sha256=tdHbAEqtfCWFVT1iecfWKh61P1IvjG59F9hfC4Srr0c,4455
+codeer_cli/cli.py,sha256=ghZMn7LUxDDvb3f82mDYW5hIFLk7dtlrCrGGP40Gygw,4637
 codeer_cli/client.py,sha256=x-5sx06dgS6P8siKOTCVNM8JlBST5e6PsOD83KKkpN8,12361
 codeer_cli/constants.py,sha256=D1pV3wCoqYybrKGKeoupYjjFWLfaFviKp1yL7oh6Qso,2323
 codeer_cli/eval_.py,sha256=2Tz4qokctocZ0fqLYL8Sk9UV8yJ7p-9zYiUFljsRRCs,17478
 codeer_cli/histories.py,sha256=tk28git_peX4x703CIDU8u72JtlGaytyrtlHfxlK-7A,5979
 codeer_cli/kb.py,sha256=Ad4h65NByq5Rq5BTeMghLTKlWRhmOC2jxL0BaTGX3EM,10631
+codeer_cli/models.py,sha256=Ama9fx8hyRMdysiUNA3Ty0sYIYwzFDkOcAZg-id3-vQ,362
 codeer_cli/parse.py,sha256=qrjZn0MUTjGfucp4cwxy8Pt7WS-0x15kK5F7kWTY8Ps,21818
 codeer_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 codeer_cli/commands/_util.py,sha256=X9-9cYgnBYz94hVG4Pe9SsI97DHNv3HE5_7GlPMn93I,1708
-codeer_cli/commands/agent.py,sha256=amvfVVrbPOkbYKCGvA6EJB30C-aY6WSdfR7u7FklXbs,14793
+codeer_cli/commands/agent.py,sha256=6qtYcQYgdJE26V6Nw6parB_3RYAYXcOpPE9iJLuLGHo,15888
 codeer_cli/commands/check.py,sha256=lTxolx1mIJ8jldPhJ5FXqie9nbCLVOO-sDPOHTSy1-w,3817
 codeer_cli/commands/eval_cmd.py,sha256=Zlt_YIA3D5-Y8WL1HZ6PxZgL-TcwFTDoXvO2gv7yfOM,71989
 codeer_cli/commands/history.py,sha256=bVBlCMStTvTxG23bggASHkHKuI0RMPdiXjcrs3U04yw,16081
 codeer_cli/commands/kb.py,sha256=kVEinBVM6NN8_0djOqIQErh46dLmArwFngXMNzvGeAI,28345
+codeer_cli/commands/model.py,sha256=91LDo_YeHi3POZV7KTCkoCcgtK5p87LwrHX1lZgfCps,1698
 codeer_cli/commands/profile.py,sha256=IdlXC_6cqobsfN3JRrAnt-1OgBUsIFneS9QtR4Un6Kc,6521
-codeer_cli-0.1.9.dist-info/METADATA,sha256=XlAf4gazUUSZ8uk9YRBxOYCiJ-C13Tru02G548cqI5M,6605
-codeer_cli-0.1.9.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-codeer_cli-0.1.9.dist-info/entry_points.txt,sha256=-nXIrlm5SR5r7gg3y8AS0tN66MwmvNHsrlwLNQNGD50,47
-codeer_cli-0.1.9.dist-info/RECORD,,
+codeer_cli-0.1.10.dist-info/METADATA,sha256=OFyEgLMBpMJ2cUkG58dei40u1BBtmSEF8HdPeyGbCek,7396
+codeer_cli-0.1.10.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+codeer_cli-0.1.10.dist-info/entry_points.txt,sha256=-nXIrlm5SR5r7gg3y8AS0tN66MwmvNHsrlwLNQNGD50,47
+codeer_cli-0.1.10.dist-info/RECORD,,