codeer-cli 0.1.13__py3-none-any.whl → 0.1.15__py3-none-any.whl

codeer_cli/cli.py

@@ -3,7 +3,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 kb list|files|export|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
 """
@@ -31,6 +31,8 @@ Safe workflow for coding agents:
   codeer agent get <agent-id> --full
   codeer kb list
   codeer kb files --kb-id <kb-id>
+  codeer kb export --node-id <file-id> --file guide.md
+  codeer kb export --node-id <folder-id> --dir kb-export
   codeer eval list --agent <agent-id>
   codeer eval label-list
   codeer eval case-update --case <case-id> --input "..." --dry-run

codeer_cli/commands/eval_cmd.py

@@ -128,6 +128,12 @@ def register(subparsers):
     g.add_argument("--system-prompt-template", help="Evaluator system prompt template text")
     g.add_argument("--system-prompt-template-file", help="Path to evaluator system prompt template")
     p.add_argument("--description", default=None)
+    p.add_argument(
+        "--judge-model",
+        default=None,
+        metavar="MODEL_ID",
+        help="Judge LLM model ID (default: system default)",
+    )
     p.add_argument("--dry-run", action="store_true",
                    help="Validate inputs and print intended mutation without writing server state.")
     p.set_defaults(func=run_evaluator_create)
@@ -140,6 +146,18 @@ def register(subparsers):
     g.add_argument("--system-prompt-template", help="Evaluator system prompt template text")
     g.add_argument("--system-prompt-template-file", help="Path to evaluator system prompt template")
     p.add_argument("--description", default=None)
+    g = p.add_mutually_exclusive_group()
+    g.add_argument(
+        "--judge-model",
+        default=None,
+        metavar="MODEL_ID",
+        help="Set the judge LLM model ID",
+    )
+    g.add_argument(
+        "--clear-judge-model",
+        action="store_true",
+        help="Clear the evaluator override and use the system default judge model",
+    )
     p.add_argument("--dry-run", action="store_true",
                    help="Validate inputs and print intended mutation without writing server state.")
     p.set_defaults(func=run_evaluator_update)
@@ -249,6 +267,7 @@ def _evaluator_summary(evaluator: dict, *, full: bool = False) -> dict:
         "id": evaluator.get("id"),
         "name": evaluator.get("name"),
         "description": evaluator.get("description"),
+        "judge_llm_model_id": evaluator.get("judge_llm_model_id"),
         "system_prompt_template_chars": len(template),
         "has_tool_steps_placeholder": "{tool_steps}" in template,
         "has_output_placeholder": "{output}" in template,
@@ -534,6 +553,10 @@ def run_evaluator_create(args, client) -> int:
             "workspace_id": workspace_id,
             "name": args.name,
             "description": args.description,
+            "judge_model": {
+                "action": "set" if args.judge_model is not None else "use_system_default",
+                "model_id": args.judge_model,
+            },
             "system_prompt_template_chars": len(system_prompt_template or ""),
             "would_write_server_state": True,
             "next_step": "Review this summary, then rerun without --dry-run after approval.",
@@ -545,6 +568,7 @@ def run_evaluator_create(args, client) -> int:
         name=args.name,
         system_prompt_template=system_prompt_template,
         description=args.description,
+        judge_llm_model_id=args.judge_model,
     )
     print_json(_evaluator_summary(evaluator, full=True))
     return 0
@@ -560,13 +584,27 @@ def run_evaluator_update(args, client) -> int:
     else:
         system_prompt_template = args.system_prompt_template
 
-    if args.name is None and args.description is None and system_prompt_template is None:
+    if (
+        args.name is None
+        and args.description is None
+        and system_prompt_template is None
+        and args.judge_model is None
+        and not args.clear_judge_model
+    ):
         log(
             "error: provide at least one of --name, --description, "
-            "--system-prompt-template, --system-prompt-template-file"
+            "--system-prompt-template, --system-prompt-template-file, "
+            "--judge-model, --clear-judge-model"
         )
         return 2
 
+    if args.clear_judge_model:
+        judge_model = {"action": "clear_to_system_default", "model_id": None}
+    elif args.judge_model is not None:
+        judge_model = {"action": "set", "model_id": args.judge_model}
+    else:
+        judge_model = {"action": "unchanged"}
+
     if args.dry_run:
         print_json({
             "dry_run": True,
@@ -574,6 +612,7 @@ def run_evaluator_update(args, client) -> int:
             "evaluator_id": args.evaluator,
             "name": args.name,
             "description": args.description,
+            "judge_model": judge_model,
             "system_prompt_template_chars": (
                 len(system_prompt_template) if system_prompt_template is not None else None
             ),
@@ -582,12 +621,20 @@ def run_evaluator_update(args, client) -> int:
         })
         return 0
 
+    evaluator_kwargs: dict[str, Any] = {
+        "name": args.name,
+        "system_prompt_template": system_prompt_template,
+        "description": args.description,
+    }
+    if args.clear_judge_model:
+        evaluator_kwargs["judge_llm_model_id"] = None
+    elif args.judge_model is not None:
+        evaluator_kwargs["judge_llm_model_id"] = args.judge_model
+
     evaluator = eval_mod.update_evaluator(
         client,
         evaluator_id=args.evaluator,
-        name=args.name,
-        system_prompt_template=system_prompt_template,
-        description=args.description,
+        **evaluator_kwargs,
     )
     print_json(_evaluator_summary(evaluator, full=True))
     return 0

codeer_cli/commands/history.py

@@ -48,13 +48,17 @@ def register(subparsers):
     # codeer history conversations <id>
     p = sub.add_parser(
         "conversations",
-        help="Summarize all Chat V2 parts in a history. Complete parts/tool payloads require --out.",
+        help="Summarize persisted History parts. Complete parts/tool payloads require --out.",
     )
     p.add_argument("history_id", type=int)
     p.add_argument("--full", action="store_true",
                    help="Require --out and include longer stdout previews; the artifact is always complete.")
     p.add_argument("--out", default=None,
-                   help="Write every unmodified client-visible Chat V2 part to this file.")
+                   help="Write every persisted part allowed by the selected export contract.")
+    p.add_argument("--client-visible", action="store_true",
+                   help="Use the external client-owner Chat V2 contract instead of the management export.")
+    p.add_argument("--user", default=None,
+                   help="external_user_id required with --client-visible.")
     p.set_defaults(func=run_conversations)
 
     # codeer history negative-feedback
@@ -158,10 +162,12 @@ def _history_summary(row: dict, *, full: bool = False) -> dict:
 
 def _part_summary(part: dict, idx: int, *, full: bool = False) -> dict:
     raw_content = part.get("content")
-    if isinstance(raw_content, dict):
+    part_kind = part.get("part_kind")
+    is_tool_part = part_kind in {"tool-call", "tool-return"}
+    if is_tool_part:
+        content_value = None
+    elif isinstance(raw_content, dict):
         content_value = raw_content.get("content")
-        if content_value is None and part.get("part_kind") == "tool-call":
-            content_value = raw_content.get("args")
     else:
         content_value = raw_content
     if isinstance(content_value, str):
@@ -176,7 +182,7 @@ def _part_summary(part: dict, idx: int, *, full: bool = False) -> dict:
         "conversation_id": part.get("conversation_id"),
         "conversation_group_id": part.get("conversation_group_id"),
         "sequence": part.get("sequence"),
-        "part_kind": part.get("part_kind"),
+        "part_kind": part_kind,
         "source": part.get("source"),
         "created_at": part.get("created_at"),
         "content_preview": truncate(content, 600 if full else 240),
@@ -184,6 +190,12 @@ def _part_summary(part: dict, idx: int, *, full: bool = False) -> dict:
         "attachment_count": len(part.get("attached_files") or []),
         "feedback_count": len(part.get("feedbacks") or []),
     }
+    if is_tool_part and isinstance(raw_content, dict):
+        row.update({
+            "tool_name": raw_content.get("tool_name"),
+            "tool_call_id": raw_content.get("tool_call_id"),
+            "outcome": raw_content.get("outcome"),
+        })
     if full:
         row["feedbacks"] = [
             {
@@ -247,24 +259,49 @@ def run_get(args, client) -> int:
 
 
 def run_conversations(args, client) -> int:
-    result = chats_mod.list_messages(client, args.history_id)
-    parts = result.get("messages") or []
     if args.full and not args.out:
         log("error: full conversation payloads are unbounded; pass --out <path>")
         return 2
+    client_visible = bool(getattr(args, "client_visible", False))
+    external_user_id = getattr(args, "user", None)
+    if client_visible and not external_user_id:
+        log("error: --client-visible requires --user <external_user_id>")
+        return 2
+    if external_user_id and not client_visible:
+        log("error: --user is only valid with --client-visible")
+        return 2
+
+    if client_visible:
+        result = chats_mod.list_messages(
+            client,
+            args.history_id,
+            external_user_id=external_user_id,
+        )
+        export_mode = "client-visible"
+    else:
+        result = hist_mod.list_messages(client, args.history_id)
+        export_mode = "management"
+    parts = result.get("messages") or []
     write_json(args.out, result)
     group_ids = {
         p.get("conversation_group_id")
         for p in parts
         if p.get("conversation_group_id")
     }
+    stdout_limit = 50 if args.full else 20
+    shown_parts = parts[:stdout_limit]
     print_json({
         "history_id": args.history_id,
+        "export_mode": export_mode,
+        "export_contract": result.get("export_contract"),
+        "part_revision": result.get("part_revision"),
         "turn_count": len(group_ids),
         "part_count": len(parts),
+        "part_summaries_shown": len(shown_parts),
+        "part_summaries_truncated": len(parts) > len(shown_parts),
         "wrote_full_detail": bool(args.out),
         "stdout_is_summary": True,
-        "parts": [_part_summary(p, i, full=args.full) for i, p in enumerate(parts)],
+        "parts": [_part_summary(p, i, full=args.full) for i, p in enumerate(shown_parts)],
     })
     return 0
 

codeer_cli/commands/kb.py

@@ -6,6 +6,7 @@ import time
 from pathlib import Path
 
 from .. import kb as kb_mod
+from ..client import AuthError, CodeerError
 from ._util import log, print_json, strip_noisy_fields, truncate, write_json
 
 POLL_INTERVAL = 3
@@ -76,6 +77,28 @@ def register(subparsers):
                    help="Write stripped full file metadata to this file; stdout stays compact unless --full.")
     p.set_defaults(func=run_files)
 
+    # codeer kb export
+    p = sub.add_parser(
+        "export",
+        help="Export available KB file snapshot contents as local UTF-8 Markdown files.",
+    )
+    p.add_argument("--node-id", required=True, help="File, folder, or KB root node UUID to export")
+    target = p.add_mutually_exclusive_group(required=True)
+    target.add_argument("--file", help="Local output path for single-file export")
+    target.add_argument("--dir", help="Local output directory for recursive folder export")
+    p.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Overwrite existing export file(s). Without this flag, the export is blocked before writing.",
+    )
+    p.add_argument("--full", action="store_true", help="Print the full per-file export manifest.")
+    p.add_argument(
+        "--out",
+        default=None,
+        help="Write the full export manifest JSON to this file; stdout stays compact unless --full.",
+    )
+    p.set_defaults(func=run_export)
+
     p = sub.add_parser("upload", help="Create/reuse KB and upload files from a directory; run --dry-run first")
     p.add_argument("--dir", required=True, help="Directory containing files to upload")
     p.add_argument("--name", required=True, help="KB display name (idempotent on name)")
@@ -334,6 +357,383 @@ def run_files(args, client) -> int:
     return 0
 
 
+_WINDOWS_RESERVED_NAMES = {
+    "CON",
+    "PRN",
+    "AUX",
+    "NUL",
+    *(f"COM{i}" for i in range(1, 10)),
+    *(f"LPT{i}" for i in range(1, 10)),
+}
+
+
+def _safe_export_component(value: str | None, *, fallback: str) -> str:
+    """Return one portable path component without allowing path traversal."""
+    raw = (value or "").strip()
+    cleaned = "".join(
+        "_" if ord(char) < 32 or char in '<>:"/\\|?*' else char
+        for char in raw
+    ).rstrip(" .")
+    if not cleaned or cleaned in {".", ".."}:
+        cleaned = fallback
+    if cleaned.split(".", 1)[0].upper() in _WINDOWS_RESERVED_NAMES:
+        cleaned = f"_{cleaned}"
+    return cleaned
+
+
+def _snapshot_filename(name: str | None, *, node_id: str) -> str:
+    safe_name = _safe_export_component(name, fallback=f"file-{node_id[:8]}")
+    if Path(safe_name).suffix.lower() not in {".md", ".markdown"}:
+        safe_name = f"{safe_name}.md"
+    return safe_name
+
+
+def _unique_export_component(component: str, *, node_id: str, used: set[str]) -> str:
+    candidate = component
+    index = 1
+    while candidate.casefold() in used:
+        suffix = f"__{node_id[:8]}" if index == 1 else f"__{node_id[:8]}-{index}"
+        path = Path(component)
+        candidate = f"{path.stem}{suffix}{path.suffix}" if path.suffix else f"{component}{suffix}"
+        index += 1
+    used.add(candidate.casefold())
+    return candidate
+
+
+def _collect_export_files(
+    client,
+    *,
+    organization_id: str,
+    workspace_id: str,
+    root_node_id: str,
+) -> tuple[list[dict], list[dict]]:
+    """Walk the KB tree and assign deterministic, collision-safe local paths."""
+    pending: list[tuple[str, tuple[str, ...], tuple[str, ...]]] = [(root_node_id, (), ())]
+    seen: set[str] = set()
+    files: list[dict] = []
+    issues: list[dict] = []
+
+    while pending:
+        parent_id, output_parts, source_parts = pending.pop()
+        if parent_id in seen:
+            issues.append({"node_id": parent_id, "reason": "cycle_or_duplicate_folder"})
+            continue
+        seen.add(parent_id)
+
+        nodes = kb_mod.list_nodes(
+            client,
+            organization_id=organization_id,
+            workspace_id=workspace_id,
+            parent_id=parent_id,
+        )
+        nodes = sorted(
+            nodes,
+            key=lambda node: (
+                str(node.get("node_type") or node.get("type") or "").upper() != "FOLDER",
+                str(node.get("name") or node.get("original_name") or "").casefold(),
+                str(node.get("id") or node.get("node_id") or ""),
+            ),
+        )
+        used_components: set[str] = set()
+        child_folders: list[tuple[str, tuple[str, ...], tuple[str, ...]]] = []
+
+        for node in nodes:
+            node_id = str(node.get("id") or node.get("node_id") or "")
+            node_type = str(node.get("node_type") or node.get("type") or "").upper()
+            node_name = str(node.get("name") or node.get("original_name") or "")
+            if not node_id:
+                issues.append({"name": node_name, "reason": "missing_node_id"})
+                continue
+
+            if node_type == "FOLDER":
+                component = _safe_export_component(node_name, fallback=f"folder-{node_id[:8]}")
+                component = _unique_export_component(component, node_id=node_id, used=used_components)
+                child_folders.append(
+                    (
+                        node_id,
+                        (*output_parts, component),
+                        (*source_parts, node_name or node_id),
+                    )
+                )
+                continue
+
+            if node_type != "FILE":
+                issues.append({"node_id": node_id, "name": node_name, "reason": f"unknown_node_type:{node_type}"})
+                continue
+
+            filename = _snapshot_filename(node_name, node_id=node_id)
+            filename = _unique_export_component(filename, node_id=node_id, used=used_components)
+            files.append(
+                {
+                    "node_id": node_id,
+                    "name": node_name,
+                    "source_path": "/".join((*source_parts, node_name or node_id)),
+                    "server_status": str(node.get("status") or "").upper() or None,
+                    "relative_output_path": str(Path(*output_parts, filename)),
+                }
+            )
+
+        pending.extend(reversed(child_folders))
+
+    files.sort(key=lambda item: item["relative_output_path"].casefold())
+    return files, issues
+
+
+def _compact_export_result(result: dict) -> dict:
+    problems = [
+        {
+            "node_id": item.get("node_id"),
+            "source_path": item.get("source_path"),
+            "result": item.get("result"),
+            "reason": item.get("reason"),
+        }
+        for item in result.get("files", [])
+        if item.get("result") != "exported"
+    ]
+    return {
+        key: result.get(key)
+        for key in (
+            "operation",
+            "mode",
+            "node_id",
+            "directory",
+            "output_file",
+            "server_status",
+            "exported_while_not_ready",
+            "complete",
+            "file_count",
+            "exported_count",
+            "non_ready_exported_count",
+            "skipped_count",
+            "failed_count",
+            "issue_count",
+            "reason",
+        )
+    } | {
+        "problems": problems[:20],
+        "additional_problem_count": max(0, len(problems) - 20),
+        "blocked_paths": result.get("blocked_paths", [])[:20],
+        "additional_blocked_path_count": max(0, len(result.get("blocked_paths", [])) - 20),
+    }
+
+
+def _print_export_result(args, result: dict) -> None:
+    write_json(args.out, result)
+    print_json(result if args.full else _compact_export_result(result))
+
+
+def _read_export_content(
+    client,
+    *,
+    organization_id: str,
+    workspace_id: str,
+    item: dict,
+) -> str | None:
+    try:
+        response = kb_mod.read_file_content(
+            client,
+            organization_id=organization_id,
+            workspace_id=workspace_id,
+            node_id=item["node_id"],
+        )
+    except AuthError:
+        raise
+    except CodeerError as exc:
+        if exc.status not in {400, 404}:
+            raise
+        item.update(result="failed", reason=f"api_error:{exc.status}:{exc.message}")
+        return None
+
+    response_status = str(response.get("status") or "").upper()
+    response_name = str(response.get("name") or "")
+    content = response.get("content")
+    item["server_status"] = response_status or item.get("server_status")
+    if response_name:
+        item["name"] = response_name
+    item.setdefault("source_path", response_name or item["node_id"])
+    if content is None:
+        item.update(
+            result="skipped",
+            reason=f"content_unavailable:{response_status or 'UNKNOWN'}",
+        )
+        return None
+    if not isinstance(content, str):
+        item.update(result="failed", reason="content_is_not_text")
+        return None
+    return content
+
+
+def _write_export_content(target: Path, content: str, item: dict) -> None:
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+    except OSError as exc:
+        item.update(result="failed", reason=f"local_write_error:{exc}")
+        return
+    item.update(
+        result="exported",
+        bytes_written=len(content.encode("utf-8")),
+        exported_while_not_ready=item.get("server_status") != "READY",
+    )
+
+
+def _export_counts(files: list[dict]) -> dict:
+    exported_count = sum(item.get("result") == "exported" for item in files)
+    return {
+        "file_count": len(files),
+        "exported_count": exported_count,
+        "non_ready_exported_count": sum(
+            item.get("result") == "exported" and item.get("server_status") != "READY"
+            for item in files
+        ),
+        "skipped_count": sum(item.get("result") == "skipped" for item in files),
+        "failed_count": sum(item.get("result") == "failed" for item in files),
+    }
+
+
+def _run_file_export(args, client, *, workspace_id: str, organization_id: str) -> int:
+    output_file = Path(args.file).expanduser().resolve()
+    if args.out and Path(args.out).expanduser().resolve() == output_file:
+        log("error: --out manifest path must differ from --file content path")
+        return 2
+    if output_file.exists() and (output_file.is_dir() or not args.overwrite):
+        log("error: single-file export blocked before writing; use --overwrite only if replacement is intended")
+        return 2
+
+    existing_parent = output_file.parent
+    while not existing_parent.exists() and existing_parent != existing_parent.parent:
+        existing_parent = existing_parent.parent
+    if existing_parent.exists() and not existing_parent.is_dir():
+        log(f"error: output parent {existing_parent} is not a directory")
+        return 2
+
+    item = {
+        "node_id": args.node_id,
+        "output_path": str(output_file),
+    }
+    content = _read_export_content(
+        client,
+        organization_id=organization_id,
+        workspace_id=workspace_id,
+        item=item,
+    )
+    if content is not None:
+        _write_export_content(output_file, content, item)
+
+    counts = _export_counts([item])
+    complete = counts["skipped_count"] == 0 and counts["failed_count"] == 0
+    result = {
+        "operation": "kb_export",
+        "mode": "file",
+        "node_id": args.node_id,
+        "directory": str(output_file.parent),
+        "output_file": str(output_file),
+        "server_status": item.get("server_status"),
+        "exported_while_not_ready": item.get("exported_while_not_ready", False),
+        "complete": complete,
+        **counts,
+        "issue_count": 0,
+        "issues": [],
+        "files": [item],
+    }
+    _print_export_result(args, result)
+    return 0 if complete else 1
+
+
+def _run_folder_export(args, client, *, workspace_id: str, organization_id: str) -> int:
+    output_dir = Path(args.dir).expanduser().resolve()
+    if output_dir.exists() and not output_dir.is_dir():
+        log(f"error: --dir {output_dir} exists and is not a directory")
+        return 2
+
+    files, issues = _collect_export_files(
+        client,
+        organization_id=organization_id,
+        workspace_id=workspace_id,
+        root_node_id=args.node_id,
+    )
+
+    blocked_paths: list[str] = []
+    for item in files:
+        target = output_dir / item["relative_output_path"]
+        if target.exists() and (target.is_dir() or not args.overwrite):
+            blocked_paths.append(str(target))
+        parent = target.parent
+        while parent != output_dir:
+            if parent.exists() and not parent.is_dir():
+                blocked_paths.append(str(parent))
+                break
+            parent = parent.parent
+
+    if blocked_paths:
+        result = {
+            "operation": "kb_export",
+            "mode": "folder",
+            "node_id": args.node_id,
+            "directory": str(output_dir),
+            "output_file": None,
+            "complete": False,
+            "file_count": len(files),
+            "exported_count": 0,
+            "non_ready_exported_count": 0,
+            "skipped_count": 0,
+            "failed_count": len(set(blocked_paths)),
+            "issue_count": len(issues),
+            "issues": issues,
+            "files": [],
+            "blocked_paths": sorted(set(blocked_paths)),
+            "reason": "existing_paths_require_overwrite_or_conflict_with_directories",
+        }
+        _print_export_result(args, result)
+        log("error: export blocked before writing; use --overwrite only if replacing existing files is intended")
+        return 2
+
+    for item in files:
+        target = output_dir / item["relative_output_path"]
+        content = _read_export_content(
+            client,
+            organization_id=organization_id,
+            workspace_id=workspace_id,
+            item=item,
+        )
+        if content is not None:
+            _write_export_content(target, content, item)
+
+    counts = _export_counts(files)
+    complete = not issues and counts["skipped_count"] == 0 and counts["failed_count"] == 0
+    result = {
+        "operation": "kb_export",
+        "mode": "folder",
+        "node_id": args.node_id,
+        "directory": str(output_dir),
+        "output_file": None,
+        "complete": complete,
+        **counts,
+        "issue_count": len(issues),
+        "issues": issues,
+        "files": files,
+    }
+    _print_export_result(args, result)
+    return 0 if complete else 1
+
+
+def run_export(args, client) -> int:
+    workspace_id, organization_id = client.resolve_scope()
+    if args.file:
+        return _run_file_export(
+            args,
+            client,
+            workspace_id=workspace_id,
+            organization_id=organization_id,
+        )
+    return _run_folder_export(
+        args,
+        client,
+        workspace_id=workspace_id,
+        organization_id=organization_id,
+    )
+
+
 def run_upload(args, client) -> int:
     workspace_id, organization_id = client.resolve_scope()
     kb_dir = Path(args.dir).resolve()

codeer_cli/eval_.py

@@ -12,6 +12,13 @@ from typing import Any, List, Optional
 from .client import CodeerClient
 
 
+class _UnsetType:
+    pass
+
+
+_UNSET = _UnsetType()
+
+
 # --- cases ----------------------------------------------------------------
 
 def create_case(
@@ -122,7 +129,7 @@ def get_case_evaluator_infos(client: CodeerClient, *, case_ids: List[str]) -> li
     Returns rows shaped like ``{"case_id": str, "evaluators": [...]}``, where
     each evaluator entry is the assigned ``{"evaluator_id", "rubric"}`` pair.
     """
-    return client.post("/eval/case-evaluator-infos:batch", json={"case_ids": case_ids})
+    return client.post("/external/eval/case-evaluator-infos:batch", json={"case_ids": case_ids})
 
 
 def replace_case_evaluator_infos(
@@ -136,7 +143,10 @@ def replace_case_evaluator_infos(
     This is intentionally separate from rubric upsert: replacing removes
     evaluator assignments that are not included in ``evaluators``.
     """
-    return client.put(f"/eval/cases/{case_id}/case-evaluator-infos", json={"evaluators": evaluators})
+    return client.put(
+        f"/external/eval/cases/{case_id}/case-evaluator-infos",
+        json={"evaluators": evaluators},
+    )
 
 
 # --- case labels -----------------------------------------------------------
@@ -186,6 +196,7 @@ def create_evaluator(
     name: str,
     system_prompt_template: str,
     description: Optional[str] = None,
+    judge_llm_model_id: Optional[str] = None,
 ) -> dict:
     body: dict[str, Any] = {
         "name": name,
@@ -193,6 +204,8 @@ def create_evaluator(
     }
     if description is not None:
         body["description"] = description
+    if judge_llm_model_id is not None:
+        body["judge_llm_model_id"] = judge_llm_model_id
     return client.post("/external/eval/evaluators", json=body)
 
 
@@ -211,6 +224,7 @@ def update_evaluator(
     name: Optional[str] = None,
     system_prompt_template: Optional[str] = None,
     description: Optional[str] = None,
+    judge_llm_model_id: str | None | _UnsetType = _UNSET,
 ) -> dict:
     body: dict[str, Any] = {}
     if name is not None:
@@ -219,6 +233,8 @@ def update_evaluator(
         body["system_prompt_template"] = system_prompt_template
     if description is not None:
         body["description"] = description
+    if judge_llm_model_id is not _UNSET:
+        body["judge_llm_model_id"] = judge_llm_model_id
     return client.put(f"/external/eval/evaluators/{evaluator_id}", json=body)
 
 

codeer_cli/histories.py

@@ -4,14 +4,15 @@ Use this after an agent has been published and running for a while, to pull
 recent traffic, filter by feedback, and feed the failing cases back into the
 evaluation loop.
 
-Pagination: ``/histories`` uses ``limit`` + ``offset`` (NOT ``page`` /
-``page_size``). Default ``limit=500`` here is a deliberate choice for analysis
-workflows — the backend caps responses anyway and returning everything in one
-call removes a common foot-gun where the caller silently truncates at 10.
+Pagination: ``/histories`` and the management parts export use ``limit`` +
+``offset`` (NOT ``page`` / ``page_size``). History metadata remains a bounded
+caller-selected page. The parts export follows every server page and rejects a
+cross-page revision change instead of returning a mixed snapshot.
 """
 
 from __future__ import annotations
 
+import builtins
 from typing import Any, Iterable, Optional
 
 from .client import CodeerClient
@@ -94,11 +95,9 @@ def list_negative_feedback_turns(
     the source channel — usually "system"). Pass the desired sentiment(s)
     in ``feedback_types``.
 
-    Cost: O(N histories) paginated Chat V2 reads. Filter aggressively via
+    Cost: O(N histories) paginated management parts reads. Filter aggressively via
     ``exclude_users`` and ``limit`` before invoking on a busy agent.
     """
-    from . import chats
-
     type_set = {t.lower() for t in feedback_types}
     histories = list(
         client,
@@ -113,10 +112,7 @@ def list_negative_feedback_turns(
         hid = h.get("id")
         if hid is None:
             continue
-        try:
-            parts = (chats.list_messages(client, hid).get("messages") or [])
-        except Exception:
-            continue
+        parts = (list_messages(client, hid).get("messages") or [])
 
         turn_indexes: dict[str, int] = {}
         user_messages: dict[str, str] = {}
@@ -158,6 +154,92 @@ def get(client: CodeerClient, history_id: int) -> dict:
     return client.get(f"/external/histories/{history_id}")
 
 
+def list_messages(
+    client: CodeerClient,
+    history_id: int,
+    *,
+    limit: int = 100,
+) -> dict:
+    """Return every persisted diagnostic part through the management export.
+
+    This route is for workspace editors analyzing a History. It is distinct
+    from the external client-owner Chat V2 route and must return the explicit
+    ``history-parts-v1`` contract. Tool calls and returns are preserved in the
+    returned artifact. System prompts and provider raw traces are outside the
+    contract.
+    """
+    if limit <= 0:
+        raise ValueError("limit must be greater than zero")
+
+    offset = 0
+    pages_fetched = 0
+    total_records: int | None = None
+    part_revision: str | None = None
+    result: dict[str, Any] | None = None
+    messages: list[dict] = []
+
+    while True:
+        page = client.get(
+            f"/external/histories/{history_id}/messages",
+            params={"limit": limit, "offset": offset},
+        )
+        if not isinstance(page, dict):
+            raise ValueError("History parts response must be an object")
+        if page.get("export_contract") != "history-parts-v1":
+            raise ValueError("History parts response is missing export_contract=history-parts-v1")
+
+        page_messages = page.get("messages")
+        page_info = page.get("page")
+        revision = page.get("part_revision")
+        if not isinstance(page_messages, builtins.list):
+            raise ValueError("History parts response must contain a messages list")
+        if not isinstance(page_info, dict):
+            raise ValueError("History parts response must contain page metadata")
+        if not isinstance(revision, str) or not revision:
+            raise ValueError("History parts response must contain part_revision")
+
+        page_offset = page_info.get("offset")
+        page_total = page_info.get("total_records")
+        page_limit = page_info.get("limit")
+        if not all(isinstance(value, int) for value in (page_offset, page_total, page_limit)):
+            raise ValueError("History parts page metadata must contain integer limit/offset/total_records")
+        if page_offset != offset:
+            raise ValueError(f"History parts page offset mismatch: requested {offset}, received {page_offset}")
+        if page_total < 0 or page_limit <= 0:
+            raise ValueError("History parts page metadata is invalid")
+
+        if total_records is None:
+            total_records = page_total
+        elif page_total != total_records:
+            raise ValueError("History parts total_records changed while paging; retry the export")
+        if part_revision is None:
+            part_revision = revision
+        elif revision != part_revision:
+            raise ValueError("History parts changed while paging; retry the export")
+
+        if result is None:
+            result = dict(page)
+        messages.extend(page_messages)
+        pages_fetched += 1
+        offset += len(page_messages)
+
+        if offset >= total_records:
+            break
+        if not page_messages:
+            raise ValueError("History parts pagination stopped before total_records was reached")
+
+    assert result is not None
+    assert total_records is not None
+    result["messages"] = messages
+    result["page"] = {
+        "limit": result["page"]["limit"],
+        "offset": 0,
+        "total_records": total_records,
+    }
+    result["pages_fetched"] = pages_fetched
+    return result
+
+
 def get_conversations(client: CodeerClient, history_id: int) -> list[dict]:
     """Return legacy V1 conversation rows.
 

codeer_cli/kb.py

@@ -234,7 +234,6 @@ def read_file_content(
     *,
     organization_id: str,
     workspace_id: str,
-    kb_id: str,
     node_id: str,
 ) -> dict:
     return client.get(f"{_base(organization_id, workspace_id)}/files/{node_id}/content")

{codeer_cli-0.1.13.dist-info → codeer_cli-0.1.15.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codeer-cli
-Version: 0.1.13
+Version: 0.1.15
 Summary: Command line tools for managing Codeer agents over the Codeer API.
 Project-URL: Homepage, https://www.codeer.ai
 Author: Codeer.AI
@@ -98,7 +98,8 @@ CODEER_AGENT_ID=<agent-id>
 
 ## Development install
 
-Use an editable install while the CLI is changing quickly:
+Codeer contributors should use an editable install from this checkout, not the
+PyPI package, so the `codeer` command always executes the folder being edited:
 
 ```bash
 cd /path/to/codeer-skills/codeer-cli
@@ -123,6 +124,34 @@ List the active cloud models without opening the Codeer web app:
 codeer model list --type text
 ```
 
+## Custom evaluator judge models
+
+Custom evaluator create/update commands can select a judge LLM model by ID:
+
+```bash
+codeer eval evaluator-create \
+  --name "Correctness" \
+  --system-prompt-template-file evaluator-prompt.txt \
+  --judge-model <model-id> \
+  --dry-run
+
+codeer eval evaluator-update \
+  --evaluator <evaluator-id> \
+  --judge-model <model-id> \
+  --dry-run
+```
+
+Omit the judge-model flags on update to leave the current setting unchanged.
+Use `--clear-judge-model` to explicitly clear the override and return to the
+system default:
+
+```bash
+codeer eval evaluator-update \
+  --evaluator <evaluator-id> \
+  --clear-judge-model \
+  --dry-run
+```
+
 ## Agent human handoff
 
 `codeer agent apply` accepts the same `human_handoff` object as the Agent API.
@@ -197,10 +226,22 @@ Flags:
   for raw eval results, full conversation turns, full rubric matrices, and
   other data that can grow with cases, versions, or turns.
 
-`history conversations` reads Chat V2 parts and follows all pages
-automatically. Its stdout is still a bounded summary; the `--out` artifact is
-the complete client-visible history, including tool calls/results,
-attachments, interactions, feedback, and passthrough metadata.
+`history conversations` defaults to the workspace-editor management export and
+follows all pages automatically. Its stdout is a bounded summary that never
+prints tool arguments or results; the `--out` artifact preserves the complete
+`history-parts-v1` payload, including persisted tool calls/results,
+attachments, feedback, and metadata. System prompts and provider raw traces are
+not part of that export contract, and a missing part does not prove that a tool
+was not executed.
+
+Use the external client-owner contract only when that distinction is the point
+of the test:
+
+```bash
+codeer history conversations <history-id> \
+  --client-visible --user <external-user-id> \
+  --out .codeer/current/client-history-<history-id>.json
+```
 
 Avoid piping large raw JSON directly into agent chat. Prefer `--out`, then ask
 the coding agent to inspect targeted summaries, IDs, failing cases, or selected
@@ -228,6 +269,45 @@ paths containing `*` so the shell passes the wildcard to the CLI. Advanced
 settings can still be passed through `--config-json`; explicit crawler flags
 override matching JSON keys.
 
+## Exporting KB snapshot content
+
+Export one file directly from the content endpoint:
+
+```bash
+codeer kb export \
+  --node-id <file-node-id> \
+  --file guide.md
+```
+
+Or recursively export a folder or an entire KB root:
+
+```bash
+codeer kb export \
+  --node-id <folder-or-kb-root-node-id> \
+  --dir kb-export \
+  --out kb-export-manifest.json
+```
+
+`--file` and `--dir` are mutually exclusive. Single-file mode maps directly to
+the external file-content endpoint and lets the caller choose the exact local
+path. Folder mode recursively lists the node tree, calls that endpoint for each
+file, and writes the extracted snapshot content as UTF-8 Markdown. Existing
+`.md`/`.markdown` names are preserved; other folder-export names receive an
+additional `.md` suffix (for example, `guide.pdf` becomes `guide.pdf.md`) so the
+export is not mistaken for the original binary upload.
+
+The command asks the content endpoint for every file regardless of indexing
+status. If the endpoint returns text, it is exported even when the status is
+not `READY`; the full manifest preserves that server status and marks the file
+as `exported_while_not_ready`. If the endpoint returns `content: null`, the file
+is skipped and the command exits non-zero. Existing target files block the
+entire export before any content is written; pass `--overwrite` only when
+replacing those local files is intended.
+
+This is a snapshot-content export, not an original-file backup. The server API
+returns processed text and does not return the original PDF, DOCX, or other
+binary bytes through this endpoint.
+
 ## KB node rename and delete
 
 Knowledge Base roots, folders, and files are all KnowledgeNodes. Use

{codeer_cli-0.1.13.dist-info → codeer_cli-0.1.15.dist-info}/RECORD

@@ -2,24 +2,24 @@ codeer_cli/__init__.py,sha256=z3rkUdVCt11c8QE3-YFkG5cFObM6QhPe2yKugA8k3aA,1915
 codeer_cli/_validate.py,sha256=lqMwkhsBy1g0o5CINBp1HdBCjMawgUaEsZygjJaAPL0,6943
 codeer_cli/agents.py,sha256=Yt_Rw4c9omsTnXsTe5n_9mD4TpDcx_1WuUkhtKmFY0g,6371
 codeer_cli/chats.py,sha256=Vg1DIu8fT6mPyPpfqLpExKvXhdZEWCyJGPvalQy3BXg,7989
-codeer_cli/cli.py,sha256=ghZMn7LUxDDvb3f82mDYW5hIFLk7dtlrCrGGP40Gygw,4637
+codeer_cli/cli.py,sha256=PDi0WLC4prkFSbY0Y7619MAdP3uoDzgTWekHrhHprHc,4756
 codeer_cli/client.py,sha256=apUycjK-OvHEquAj58FqOy8FHmHjA6K9dScaYQ4M-VU,13175
 codeer_cli/constants.py,sha256=D1pV3wCoqYybrKGKeoupYjjFWLfaFviKp1yL7oh6Qso,2323
-codeer_cli/eval_.py,sha256=2Tz4qokctocZ0fqLYL8Sk9UV8yJ7p-9zYiUFljsRRCs,17478
-codeer_cli/histories.py,sha256=WvpqvuprPc1nJJCTElyM_eoUabyooACfmRCwYlcvPnI,6637
-codeer_cli/kb.py,sha256=Ad4h65NByq5Rq5BTeMghLTKlWRhmOC2jxL0BaTGX3EM,10631
+codeer_cli/eval_.py,sha256=TjDFGCGF19JaUmSaP3PiKIRrBIvYaU-EJS4dC-N7eBI,17868
+codeer_cli/histories.py,sha256=Tom4tM20mls-Jo-q7NXish3zeOyMM5Nkd7MZjHFfy88,9979
+codeer_cli/kb.py,sha256=-HodcGwTvIKgvuRVc5sPFu51si-GlzLEsPSHmnfrVQU,10615
 codeer_cli/models.py,sha256=Ama9fx8hyRMdysiUNA3Ty0sYIYwzFDkOcAZg-id3-vQ,362
 codeer_cli/parse.py,sha256=-txMtIxPfeg_i4McEskVKxo8p4438gKS-sFTI38RoBs,21772
 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=BjctOF0tflt8yVGzdc6320sWXVUAYrF39tNIiTxtQx4,16319
 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=2p9VuPwyexr7Q2FFIBSuv9hNzn7VdIMa-AtvtP-8LvI,17253
-codeer_cli/commands/kb.py,sha256=kVEinBVM6NN8_0djOqIQErh46dLmArwFngXMNzvGeAI,28345
+codeer_cli/commands/eval_cmd.py,sha256=S-ydzWZppPLMCu2i_HOK0OW5ZaoebxcLO--WDYOIuAk,73548
+codeer_cli/commands/history.py,sha256=jUm0ZnIaJc0FV7pwMNdCBuuKPoauhDY2swFqB6_byWU,18800
+codeer_cli/commands/kb.py,sha256=1lwrKTC0NpnAvXZ0u5DPsfx7ZXcHLURyBrqRViv03Yk,42349
 codeer_cli/commands/model.py,sha256=91LDo_YeHi3POZV7KTCkoCcgtK5p87LwrHX1lZgfCps,1698
 codeer_cli/commands/profile.py,sha256=IdlXC_6cqobsfN3JRrAnt-1OgBUsIFneS9QtR4Un6Kc,6521
-codeer_cli-0.1.13.dist-info/METADATA,sha256=zslhdIB39lnbLxfGOM9sv8zrZdzDNzi6xjZWCDLrPQU,7885
-codeer_cli-0.1.13.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-codeer_cli-0.1.13.dist-info/entry_points.txt,sha256=-nXIrlm5SR5r7gg3y8AS0tN66MwmvNHsrlwLNQNGD50,47
-codeer_cli-0.1.13.dist-info/RECORD,,
+codeer_cli-0.1.15.dist-info/METADATA,sha256=Cwz2jFmIb0GSVClvWt3WqfKm-F_SRvO7W6n67d6t7AY,10673
+codeer_cli-0.1.15.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+codeer_cli-0.1.15.dist-info/entry_points.txt,sha256=-nXIrlm5SR5r7gg3y8AS0tN66MwmvNHsrlwLNQNGD50,47
+codeer_cli-0.1.15.dist-info/RECORD,,