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

codeer_cli/_http_contracts.py

@@ -0,0 +1,109 @@
+"""HTTP input *configuration* checks; value conversion belongs to the server.
+
+Key generation follows collect_http_request_agent_placeholders in the backend's
+http_request/execution.py. Keep its traversal and collision rules in sync.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+_AGENT_PLACEHOLDER_RE = re.compile(r"\{\{\s*agent\[(.*?)\]\s*\}\}")
+_CONTRACT_FIELDS = {
+    "type": ("string", "number", "integer", "boolean", "object", "array"),
+    "format": ("text", "json"),
+    "json_type": ("any", "object", "array"),
+}
+
+
+def _contract_defaults(contract: Any, key: str) -> dict[str, str]:
+    prefix = f"input_contracts[{key!r}]"
+    if not isinstance(contract, dict):
+        raise ValueError(f"{prefix} must be an object.")
+    if any(field not in _CONTRACT_FIELDS for field in contract):
+        raise ValueError(
+            f"{prefix} accepts only type, format, json_type (snake_case, not jsonType)."
+        )
+    resolved = {}
+    for field, choices in _CONTRACT_FIELDS.items():
+        value = contract.get(field, choices[0])
+        if not isinstance(value, str) or value not in choices:
+            raise ValueError(f"{prefix}.{field} must be one of: {', '.join(choices)}.")
+        resolved[field] = value
+    if resolved["format"] == "json" and resolved["type"] != "string":
+        raise ValueError(f"{prefix}: format=json is only available for type=string.")
+    if resolved["format"] != "json" and resolved["json_type"] != "any":
+        raise ValueError(f"{prefix}: json_type requires format=json unless it is any.")
+    return resolved
+
+
+def validate_http_input_contracts(body: Any) -> list[dict[str, Any]]:
+    """Validate without mutation and return value-free input format summaries.
+
+    An omitted body is supplied as {} by callers; template may be null/absent.
+    Unconfigured placeholders retain string/text/any, including mixed text.
+    Unknown body fields follow the backend's existing ignore policy, except the
+    frontend alias inputContracts: reject it rather than silently losing intent.
+    Contract entries themselves are strict and reject all unknown fields.
+    """
+    if not isinstance(body, dict):
+        raise ValueError("body must be an object; omit it for no body.")
+    if "inputContracts" in body:
+        raise ValueError("use input_contracts (snake_case), not inputContracts.")
+    contracts = body.get("input_contracts", {})
+    if not isinstance(contracts, dict) or any(
+        not isinstance(key, str) for key in contracts
+    ):
+        raise ValueError("input_contracts must be an object with string keys.")
+    resolved = {
+        key: _contract_defaults(contract, key) for key, contract in contracts.items()
+    }
+    summaries: list[dict[str, Any]] = []
+    used_keys: set[str] = set()
+
+    def walk(value: Any, path: str) -> None:
+        if isinstance(value, dict):
+            for key, item in value.items():
+                walk(item, f"{path}.{key}" if path else key)
+            return
+        if isinstance(value, list):
+            for index, item in enumerate(value):
+                walk(item, f"{path}[{index}]")
+            return
+        if not isinstance(value, str):
+            return
+
+        matches = list(_AGENT_PLACEHOLDER_RE.finditer(value))
+        for index, match in enumerate(matches):
+            if not match.group(1).strip():
+                raise ValueError("Agent placeholder instruction cannot be empty.")
+            base = (
+                re.sub(r"[^a-zA-Z0-9]+", "_", path or "body").strip("_").lower()
+                or "body"
+            )
+            if len(matches) > 1:
+                base = f"{base}_{index + 1}"
+            key = base
+            suffix = 2
+            while key in used_keys:
+                key = f"{base}_{suffix}"
+                suffix += 1
+            used_keys.add(key)
+            contract = resolved.get(key) or _contract_defaults({}, key)
+            if (contract["type"] != "string" or contract["format"] == "json") and (
+                len(matches) != 1 or match.group(0) != value
+            ):
+                raise ValueError(
+                    f"Input {key!r}: typed and JSON-text inputs must occupy the entire template value."
+                )
+            summaries.append({"key": key, **contract, "configured": key in contracts})
+
+    walk(body.get("template"), "")
+    if set(contracts) - used_keys:
+        raise ValueError(
+            "input_contracts contains keys that do not match current placeholders; "
+            "remove stale contracts or regenerate keys after changing template paths/order."
+        )
+    return summaries

codeer_cli/_validate.py

@@ -3,13 +3,15 @@
 These checks exist because the backend's form-schema validator is lenient
 (``extra="allow"``) and silently accepts unknown ``type`` strings, which then
 render as blank fields in the web builder. Catching the common mistakes here
-gives actionable errors before the PUT/POST round-trip.
+gives actionable errors before the PATCH/POST round-trip. HTTP input contracts
+also need strict configuration checks before a draft is saved.
 """
 
 from __future__ import annotations
 
 from typing import Any, Iterable
 
+from ._http_contracts import validate_http_input_contracts
 from .constants import (
     FORM_FIELD_TYPES,
     MAX_CALL_AGENT_TOOLS,
@@ -121,10 +123,14 @@ def _validate_single_tool(tool: dict[str, Any], index: int) -> None:
             raise ToolValidationError(f"{prefix}: call_agent tool requires agent_id.")
     elif tool_type == "http_request":
         cfg = tool.get("http_request")
-        if not cfg or not cfg.get("method") or not cfg.get("url_template"):
+        if not isinstance(cfg, dict) or not cfg.get("method") or not cfg.get("url_template"):
             raise ToolValidationError(
                 f"{prefix}: http_request tool requires http_request.method and http_request.url_template."
             )
+        try:
+            validate_http_input_contracts(cfg.get("body", {}))
+        except ValueError as exc:
+            raise ToolValidationError(f"{prefix}.http_request.body: {exc}") from None
 
 
 def _validate_form_schema(schema: Any, prefix: str) -> None:

codeer_cli/agents.py

@@ -66,7 +66,7 @@ def update(
     attachment_ids: Optional[List[str]] = None,
     human_handoff: Optional[dict[str, Any]] = None,
 ) -> dict:
-    """PUT creates a new AgentHistory snapshot (draft)."""
+    """PATCH replaces settings and creates a draft; unified_tools is the full list."""
     validated_tools = validate_unified_tools(unified_tools)
     validated_handoff = validate_human_handoff(human_handoff)
     body: dict[str, Any] = {

codeer_cli/cli.py

@@ -5,7 +5,7 @@
     codeer model list
     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
+    codeer history list|get|conversations|ai-drafts|negative-feedback|create|send
 """
 
 from __future__ import annotations
@@ -16,6 +16,7 @@ import sys
 
 from .client import AuthError, CodeerClient, CodeerError
 from .commands import check
+from .histories import HistoryExportError
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -127,6 +128,9 @@ Use --out <path> for large raw artifacts; stdout defaults to compact summaries.
 
     try:
         return args.func(args, client)
+    except HistoryExportError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
     except AuthError as e:
         print(f"auth: {e}", file=sys.stderr)
         return 3

codeer_cli/client.py

@@ -161,6 +161,7 @@ class CodeerClient:
         files: Any = None,
         data: Any = None,
         timeout: Optional[float] = None,
+        unwrap: bool = True,
     ) -> Any:
         url = _api_url(path, api_version=api_version)
         request_kwargs: dict[str, Any] = {}
@@ -186,7 +187,7 @@ class CodeerClient:
             ) from exc
         except httpx.RequestError as exc:
             raise self._transport_error(method_upper, path, exc) from exc
-        return self._parse(r)
+        return self._parse(r, unwrap=unwrap)
 
     def get(self, path: str, **kwargs: Any) -> Any:
         return self.request("GET", path, **kwargs)
@@ -290,7 +291,7 @@ class CodeerClient:
             },
         )
 
-    def _parse(self, r: httpx.Response) -> Any:
+    def _parse(self, r: httpx.Response, *, unwrap: bool = True) -> Any:
         text = r.text
         try:
             payload = r.json() if text else None
@@ -306,7 +307,7 @@ class CodeerClient:
         if isinstance(payload, dict) and "error_code" in payload and "data" in payload:
             if payload.get("error_code") not in (0, None):
                 raise CodeerError(r.status_code, payload.get("message") or "error", payload)
-            return payload["data"]
+            return payload["data"] if unwrap else payload
         return payload
 
     def _raise_for_error(self, status: int, payload: Any) -> None:

codeer_cli/commands/_util.py

@@ -34,7 +34,12 @@ NOISY_KEYS = {
 
 
 def strip_noisy_fields(value: Any) -> Any:
-    """Remove server/account metadata that is not useful for agent lifecycle work."""
+    """Simplify metadata on one API resource (or a list of resources).
+
+    Callers pass unwrapped resource records, not response envelopes. Nested
+    dictionaries are opaque content: templates, schemas, tool results and other
+    user data can legally contain any of the metadata names. Do not recurse.
+    """
     if isinstance(value, list):
         return [strip_noisy_fields(item) for item in value]
     if not isinstance(value, dict):
@@ -51,7 +56,7 @@ def strip_noisy_fields(value: Any) -> Any:
                 if item.get(k) is not None
             }
             continue
-        out[key] = strip_noisy_fields(item)
+        out[key] = item
     return out
 
 

codeer_cli/commands/agent.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Optional
 
 from .. import agents as agents_mod
+from .._http_contracts import validate_http_input_contracts
 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
@@ -32,6 +33,7 @@ def register(subparsers):
         help="Read one agent. Defaults to summary; use --full for prompt/tool detail or --out for an artifact.",
     )
     p.add_argument("agent_id")
+    p.add_argument("--history", default=None, help="Read this exact AgentHistory UUID instead of the editable agent.")
     p.add_argument("--full", action="store_true",
                    help="Print stripped full agent config, including system_prompt and tools.")
     p.add_argument("--out", default=None,
@@ -41,8 +43,8 @@ def register(subparsers):
     # codeer agent apply --payload agent.json
     p = sub.add_parser("apply", help="Create or update agent from JSON payload; run --dry-run first")
     p.add_argument("--payload", required=True, help="Path to agent payload JSON")
-    p.add_argument("--agent-id", default=None, help="If set, PUT (update). Else POST (create).")
-    p.add_argument("--note", default="", help="version_note for PUT")
+    p.add_argument("--agent-id", default=None, help="If set, PATCH (update). Else POST (create).")
+    p.add_argument("--note", default="", help="version_note for PATCH")
     p.add_argument("--dry-run", action="store_true",
                    help="Validate payload and print intended mutation without writing server state.")
     p.add_argument("--out", default=None, help="Write result JSON to this file too")
@@ -61,13 +63,13 @@ def register(subparsers):
     # codeer agent versions --agent <id>
     p = sub.add_parser(
         "versions",
-        help="List version history. Defaults to version metadata only; use --out for full snapshots.",
+        help="List version metadata; use agent get --history <id> for a stored snapshot.",
     )
     p.add_argument("--agent", required=True)
     p.add_argument("--full", action="store_true",
-                   help="Add bounded prompt/tool size metadata; full snapshots still require --out.")
+                   help="Add prompt/tool size metadata when included by the server.")
     p.add_argument("--out", default=None,
-                   help="Write stripped full version snapshots to this file; stdout stays compact.")
+                   help="Write the full version listing (metadata, not snapshots); stdout stays compact.")
     p.set_defaults(func=run_versions)
 
     p = sub.add_parser("impact", help="Check downstream agents affected by this agent")
@@ -130,6 +132,8 @@ def _agent_summary(agent: dict, *, full: bool = False) -> dict:
         "human_handoff_enabled": bool(human_handoff.get("enabled")),
         "system_prompt_chars": len(agent.get("system_prompt") or ""),
     }
+    if "version_number" in agent:
+        row.update({key: agent.get(key) for key in ("agent_id", "version_number", "status")})
     if full:
         row["description"] = agent.get("description") or ""
         row["use_search"] = agent.get("use_search")
@@ -150,7 +154,11 @@ def run_list(args, client) -> int:
 
 
 def run_get(args, client) -> int:
-    result = agents_mod.get(client, args.agent_id)
+    history_id = getattr(args, "history", None)
+    result = (
+        agents_mod.get_version(client, args.agent_id, history_id)
+        if history_id else agents_mod.get(client, args.agent_id)
+    )
     full_result = strip_noisy_fields(result)
     write_json(args.out, full_result)
     print_json(full_result if args.full else _agent_summary(result))
@@ -183,6 +191,15 @@ def run_apply(args, client) -> int:
             "name": body.get("name"),
             "system_prompt_chars": len(body.get("system_prompt") or ""),
             "tool_count": len(validated_tools),
+            "http_inputs": [
+                {
+                    "tool_index": index,
+                    "body_inputs_used": tool["http_request"]["method"] not in ("GET", "HEAD"),
+                    "inputs": validate_http_input_contracts(tool["http_request"].get("body", {})),
+                }
+                for index, tool in enumerate(validated_tools)
+                if tool.get("type") == "http_request"
+            ],
             "use_search": body.get("use_search", False),
             "llm_model": body.get("llm_model"),
             "llm_model_settings_provided": llm_model_settings_provided,
@@ -223,7 +240,7 @@ def run_apply(args, client) -> int:
             **model_settings_kwargs,
         )
         agent_id = args.agent_id
-        log(f"PUT /agents/{agent_id} ok")
+        log(f"PATCH /agents/{agent_id} ok")
     else:
         if not body.get("workspace_id"):
             body["workspace_id"] = client.resolve_scope()[0]
@@ -274,8 +291,10 @@ def run_versions(args, client) -> int:
             "created_at": v.get("created_at"),
         }
         if args.full:
-            row["system_prompt_chars"] = len(v.get("system_prompt") or "")
-            row["tool_count"] = len(v.get("unified_tools") or v.get("tools") or [])
+            if "system_prompt" in v:
+                row["system_prompt_chars"] = len(v.get("system_prompt") or "")
+            if "unified_tools" in v or "tools" in v:
+                row["tool_count"] = len(v.get("unified_tools") or v.get("tools") or [])
         rows.append(row)
     print_json(rows)
     return 0
@@ -371,7 +390,9 @@ def _summarize_tool(t: dict) -> str:
                  "knowledge_node_ids", "domain", "agent_id",
                  "custom_form_schema", "http_request")
     safe = {k: t.get(k) for k in keep_keys if t.get(k) is not None}
-    return json.dumps(safe, ensure_ascii=False, indent=2, sort_keys=True)
+    # HTTP placeholder keys depend on template insertion order. Sorting would
+    # hide a reordering that changes which input receives a collision suffix.
+    return json.dumps(safe, ensure_ascii=False, indent=2, sort_keys=t.get("type") != "http_request")
 
 
 def run_diff(args, client) -> int:

codeer_cli/commands/history.py

@@ -23,6 +23,8 @@ def register(subparsers):
     p.add_argument("--agent", default=None)
     p.add_argument("--user", default=None, help="Filter by external_user_id")
     p.add_argument("--feedback", default=None, help="positive / negative / any")
+    p.add_argument("--has-ai-drafts", action="store_true",
+                   help="Only list histories with at least one AI Draft.")
     p.add_argument("--exclude-users", default=None,
                    help="Comma-separated external_user_ids to exclude")
     p.add_argument("--version", type=int, default=None,
@@ -61,6 +63,18 @@ def register(subparsers):
                    help="external_user_id required with --client-visible.")
     p.set_defaults(func=run_conversations)
 
+    # codeer history ai-drafts <id>
+    p = sub.add_parser(
+        "ai-drafts",
+        help="Export every paginated AI Draft lifecycle record returned for one History.",
+    )
+    p.add_argument("history_id", type=int)
+    p.add_argument("--full", action="store_true",
+                   help="Require --out and opt into sensitive content previews on stdout.")
+    p.add_argument("--out", default=None,
+                   help="Write every AI Draft record, refinement signal, outcome, tool activity, and delivery.")
+    p.set_defaults(func=run_ai_drafts)
+
     # codeer history negative-feedback
     p = sub.add_parser("negative-feedback", help="Surface assistant turns with negative feedback")
     p.add_argument("--agent", required=True)
@@ -148,6 +162,15 @@ def _history_summary(row: dict, *, full: bool = False) -> dict:
         "feedback_counts": _feedback_counts(row),
         "snippet_preview": truncate(row.get("snippet") or "", 240),
     }
+    for key in (
+        "ai_draft_count",
+        "dismissed_draft_count",
+        "regenerated_draft_count",
+        "applied_draft_count",
+        "sent_from_ai_draft_count",
+    ):
+        if key in row:
+            out[key] = row.get(key)
     if full:
         out["share_type"] = row.get("share_type")
         meta = row.get("meta") or {}
@@ -190,6 +213,9 @@ 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:
+        # Exact tool payloads belong in the artifact, never terminal previews.
+        row.pop("content_preview", None)
     if is_tool_part and isinstance(raw_content, dict):
         row.update({
             "tool_name": raw_content.get("tool_name"),
@@ -224,6 +250,7 @@ def run_list(args, client) -> int:
         organization_id=organization_id,
         external_user_id=args.user,
         feedback_filter=args.feedback,
+        has_ai_drafts=True if getattr(args, "has_ai_drafts", False) else None,
         exclude_users=exclude,
         limit=args.limit,
         offset=args.offset,
@@ -301,11 +328,80 @@ def run_conversations(args, client) -> int:
         "part_summaries_truncated": len(parts) > len(shown_parts),
         "wrote_full_detail": bool(args.out),
         "stdout_is_summary": True,
+        "read_contract": result.get("export_contract") or "client-visible-chat-v2",
+        "provider_raw_trace": result.get("provider_raw_trace", "not_included"),
+        "missing_parts_do_not_prove_non_execution": True,
+        "omitted_part_summaries": len(parts) - len(shown_parts),
         "parts": [_part_summary(p, i, full=args.full) for i, p in enumerate(shown_parts)],
     })
     return 0
 
 
+def _ai_draft_summary(draft: dict, *, full: bool = False) -> dict:
+    delivery = draft.get("delivery") or {}
+    row = {
+        "id": draft.get("id"),
+        "history_id": draft.get("history_id"),
+        "thread_key": draft.get("thread_key"),
+        "context_through_sequence": draft.get("context_through_sequence"),
+        "outcome": draft.get("outcome"),
+        "result_type": draft.get("result_type"),
+        "refinement_source_draft_id": draft.get("refinement_source_draft_id"),
+        "has_generation_instruction": bool(draft.get("generation_instruction")),
+        "dismiss_reason": draft.get("dismiss_reason"),
+        "has_dismiss_feedback": bool(draft.get("dismiss_feedback")),
+        "has_generated_content": bool(draft.get("content")),
+        "has_actual_content": bool(delivery.get("actual_content")),
+        "delivery_status": delivery.get("status"),
+        "tool_activity_count": len(draft.get("tool_activities") or []),
+        "has_proposed_actions": draft.get("proposed_actions") is not None,
+        "created_at": draft.get("created_at"),
+    }
+    if full:
+        row.update({
+            "generation_instruction_preview": truncate(draft.get("generation_instruction") or "", 600),
+            "dismiss_feedback_preview": truncate(draft.get("dismiss_feedback") or "", 600),
+            "content_preview": truncate(draft.get("content") or "", 600),
+            "actual_content_preview": truncate(delivery.get("actual_content") or "", 600),
+        })
+    return row
+
+
+def run_ai_drafts(args, client) -> int:
+    if args.full and not args.out:
+        log("error: AI Draft content previews require --out <path>")
+        return 2
+
+    result = hist_mod.list_ai_drafts(client, args.history_id)
+    drafts = result["drafts"]
+    write_json(args.out, result)
+    stdout_limit = 50 if args.full else 20
+    shown_drafts = drafts[:stdout_limit]
+    outcome_counts: dict[str, int] = {}
+    for draft in drafts:
+        outcome = str(draft.get("outcome") or "unknown")
+        outcome_counts[outcome] = outcome_counts.get(outcome, 0) + 1
+    print_json({
+        "history_id": args.history_id,
+        "draft_count": len(drafts),
+        "outcome_counts": outcome_counts,
+        "regenerated_draft_count": sum(
+            1 for draft in drafts if draft.get("refinement_source_draft_id") is not None
+        ),
+        "sent_from_ai_draft_count": sum(
+            1 for draft in drafts if (draft.get("delivery") or {}).get("status") == "sent"
+        ),
+        "draft_summaries_shown": len(shown_drafts),
+        "draft_summaries_truncated": len(drafts) > len(shown_drafts),
+        "pages_fetched": result["pages_fetched"],
+        "snapshot_consistency": result.get("snapshot_consistency", "best-effort"),
+        "wrote_full_detail": bool(args.out),
+        "stdout_is_summary": True,
+        "drafts": [_ai_draft_summary(draft, full=args.full) for draft in shown_drafts],
+    })
+    return 0
+
+
 def run_negative_feedback(args, client) -> int:
     exclude = _parse_exclude(args.exclude_users)
     workspace_id, organization_id = client.resolve_scope()

codeer_cli/histories.py

@@ -4,10 +4,12 @@ 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`` 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.
+Pagination: ``/histories``, AI Draft lifecycle export, and the management parts
+export use ``limit`` + ``offset`` (NOT ``page`` / ``page_size``). History
+metadata remains a bounded caller-selected page. Draft and parts exports follow
+every server page. The parts export additionally rejects a cross-page revision
+change instead of returning a mixed snapshot. The AI Draft endpoint does not
+provide a revision token, so its multi-page export is explicitly best-effort.
 """
 
 from __future__ import annotations
@@ -15,7 +17,11 @@ from __future__ import annotations
 import builtins
 from typing import Any, Iterable, Optional
 
-from .client import CodeerClient
+from .client import CodeerClient, CodeerError
+
+
+class HistoryExportError(ValueError):
+    """The server cannot provide a complete, consistent History parts export."""
 
 
 def list(
@@ -26,6 +32,7 @@ def list(
     organization_id: Optional[str] = None,
     external_user_id: Optional[str] = None,
     feedback_filter: Optional[str] = None,
+    has_ai_drafts: Optional[bool] = None,
     exclude_users: Iterable[str] = (),
     limit: int = 500,
     offset: int = 0,
@@ -48,6 +55,8 @@ def list(
         params["external_user_id"] = external_user_id
     if feedback_filter:
         params["feedback_filter"] = feedback_filter
+    if has_ai_drafts is not None:
+        params["has_ai_drafts"] = has_ai_drafts
     rows = client.get("/external/histories", params=params)
     drop = {e.lower() for e in exclude_users}
     if drop:
@@ -55,6 +64,85 @@ def list(
     return rows
 
 
+def list_ai_drafts(client: CodeerClient, history_id: int, *, limit: int = 500) -> dict[str, Any]:
+    """Export every AI Draft lifecycle record returned while paging one History.
+
+    The endpoint returns pagination beside ``data`` in the standard response
+    envelope, so this read explicitly preserves the envelope and follows the
+    server-reported page size. Draft rows are returned unmodified. Count changes
+    and duplicate IDs are rejected, but without a server revision token this is
+    not a transactionally consistent point-in-time snapshot.
+    """
+    if limit <= 0:
+        raise ValueError("limit must be greater than zero")
+
+    offset = 0
+    pages_fetched = 0
+    total_records: int | None = None
+    drafts: list[dict] = []
+    seen_ids: set[Any] = set()
+
+    while True:
+        envelope = client.get(
+            f"/external/histories/{history_id}/ai-drafts",
+            params={"limit": limit, "offset": offset},
+            unwrap=False,
+        )
+        if not isinstance(envelope, dict):
+            raise ValueError("AI Draft response must be an envelope object")
+        page_drafts = envelope.get("data")
+        page_info = envelope.get("pagination")
+        if not isinstance(page_drafts, builtins.list):
+            raise ValueError("AI Draft response must contain a data list")
+        if not isinstance(page_info, dict):
+            raise ValueError("AI Draft response must contain pagination metadata")
+
+        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("AI Draft pagination must contain integer limit/offset/total_records")
+        if page_offset != offset:
+            raise ValueError(f"AI Draft page offset mismatch: requested {offset}, received {page_offset}")
+        if page_total < 0 or page_limit <= 0:
+            raise ValueError("AI Draft pagination metadata is invalid")
+
+        if total_records is None:
+            total_records = page_total
+        elif page_total != total_records:
+            raise ValueError("AI Draft total_records changed while paging; retry the export")
+        if len(page_drafts) > page_limit or offset + len(page_drafts) > total_records:
+            raise ValueError("AI Draft page contains more rows than its pagination metadata allows")
+
+        for draft in page_drafts:
+            if not isinstance(draft, dict):
+                raise ValueError("AI Draft data rows must be objects")
+            draft_id = draft.get("id")
+            if not isinstance(draft_id, int):
+                raise ValueError("AI Draft data rows must contain an integer id")
+            if draft_id in seen_ids:
+                raise ValueError("AI Draft pagination returned a duplicate draft id")
+            seen_ids.add(draft_id)
+            drafts.append(draft)
+
+        pages_fetched += 1
+        offset += len(page_drafts)
+        if offset >= total_records:
+            break
+        if not page_drafts:
+            raise ValueError("AI Draft pagination stopped before total_records was reached")
+
+    assert total_records is not None
+    return {
+        "history_id": history_id,
+        "source_endpoint": f"/api/v1/external/histories/{history_id}/ai-drafts",
+        "snapshot_consistency": "best-effort",
+        "total_records": total_records,
+        "pages_fetched": pages_fetched,
+        "drafts": drafts,
+    }
+
+
 def list_negative_feedback_turns(
     client: CodeerClient,
     *,
@@ -162,14 +250,14 @@ def list_messages(
 ) -> dict:
     """Return every persisted diagnostic part through the management export.
 
-    This route is for workspace editors analyzing a History. It is distinct
+    This route requires a workspace admin API key to analyze 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")
+        raise HistoryExportError("limit must be greater than zero")
 
     offset = 0
     pages_fetched = 0
@@ -179,43 +267,54 @@ def list_messages(
     messages: list[dict] = []
 
     while True:
-        page = client.get(
-            f"/external/histories/{history_id}/messages",
-            params={"limit": limit, "offset": offset},
-        )
+        try:
+            page = client.get(
+                f"/external/histories/{history_id}/messages",
+                params={"limit": limit, "offset": offset},
+            )
+        except CodeerError as exc:
+            if exc.status == 404:
+                raise CodeerError(404,
+                    "History or its parts export endpoint is unavailable. "
+                    "This command requires a server supporting history-parts-v1; no fallback was attempted.",
+                    exc.body) from exc
+            raise
         if not isinstance(page, dict):
-            raise ValueError("History parts response must be an object")
+            raise HistoryExportError("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")
+            raise HistoryExportError("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")
+            raise HistoryExportError("History parts response must contain a messages list")
         if not isinstance(page_info, dict):
-            raise ValueError("History parts response must contain page metadata")
+            raise HistoryExportError("History parts response must contain page metadata")
         if not isinstance(revision, str) or not revision:
-            raise ValueError("History parts response must contain part_revision")
+            raise HistoryExportError("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")
+            raise HistoryExportError("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}")
+            raise HistoryExportError(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")
+            raise HistoryExportError("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")
+            raise HistoryExportError("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")
+            raise HistoryExportError("History parts changed while paging; retry the export")
+
+        if len(page_messages) > page_limit or offset + len(page_messages) > total_records:
+            raise HistoryExportError("History parts page contains more rows than its pagination metadata allows")
 
         if result is None:
             result = dict(page)
@@ -223,10 +322,10 @@ def list_messages(
         pages_fetched += 1
         offset += len(page_messages)
 
-        if offset >= total_records:
+        if offset == total_records:
             break
-        if not page_messages:
-            raise ValueError("History parts pagination stopped before total_records was reached")
+        if len(page_messages) != page_limit:
+            raise HistoryExportError("Incomplete History messages page")
 
     assert result is not None
     assert total_records is not None

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codeer-cli
-Version: 0.1.15
+Version: 0.1.16
 Summary: Command line tools for managing Codeer agents over the Codeer API.
 Project-URL: Homepage, https://www.codeer.ai
 Author: Codeer.AI
@@ -175,6 +175,104 @@ 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.
 
+## HTTP input contracts
+
+`codeer agent apply --payload` and SDK `agents.create` / `agents.update` accept
+`unified_tools[].http_request.body.input_contracts`. No separate HTTP command is
+needed. The target backend must have the HTTP input-contract feature deployed
+(codeer-copilot #1495); installing this CLI alone does not enable runtime support.
+A local dry-run cannot establish server deployment or API business-rule success.
+
+Example payload:
+
+```json
+{
+  "name": "Order helper",
+  "system_prompt": "Use the configured API for approved order changes.",
+  "use_search": false,
+  "unified_tools": [{
+    "id": "submit",
+    "type": "http_request",
+    "http_request": {
+      "method": "POST",
+      "url_template": "https://example.com/orders",
+      "body": {
+        "template": {
+          "quantity": "{{agent[Requested quantity]}}",
+          "payload": "{{agent[Order details]}}",
+          "changes": "{{agent[Changes as JSON text]}}"
+        },
+        "input_contracts": {
+          "quantity": {"type": "integer"},
+          "payload": {"type": "object"},
+          "changes": {"type": "string", "format": "json", "json_type": "array"}
+        }
+      }
+    }
+  }]
+}
+```
+
+- `type`: `string` (default), `number`, `integer`, `boolean`, `object`, `array`.
+- `format`: `text` (default) or `json`; `json` requires `type: string`.
+- `json_type`: `any` (default), `object`, `array`; outside JSON format, only
+  `any` is valid. API names are snake_case; the CLI rejects `inputContracts`,
+  `jsonType`, and unknown fields inside individual contracts.
+
+`type: object` / `array` sends a native JSON value. `type: string, format: json`
+sends a string containing JSON. Existing valid JSON text is sent unchanged;
+empty strings also pass unchanged, while non-empty text must parse and match
+`json_type`. Plain strings retain existing behavior, including malformed JSON.
+The backend converts supported representations before checking runtime values;
+the CLI only validates configuration and never executes the configured HTTP
+request. Contracts do not configure nested JSON Schema constraints or defaults.
+
+Keys come from template paths, not instructions: `order.count` → `order_count`,
+`items[0].id` → `items_0_id`, root string → `body`. Non-ASCII-alphanumeric runs
+become `_`, edge underscores are removed, and keys are lowercased. Multiple
+placeholders in one string add `_1`, `_2`; traversal collisions add `_2`, `_3`.
+Object insertion order matters: preserve it when editing/exporting. Typed and
+JSON-text placeholders must occupy the entire template value. Stale contract
+keys fail validation; omitted entries remain ordinary strings.
+
+For an existing Agent:
+
+```bash
+codeer agent get <agent-id> --out .codeer/current/agent.json
+# Prepare local_draft_agent.json from current writable settings; review its diff.
+codeer agent apply --agent-id <agent-id> --payload .codeer/current/local_draft_agent.json --dry-run
+# After approval:
+codeer agent apply --agent-id <agent-id> --payload .codeer/current/local_draft_agent.json
+codeer agent get <agent-id> --out .codeer/current/agent.json
+codeer agent get <agent-id> --history <history-id-from-apply> --out .codeer/current/agent-version.json
+```
+
+The external update uses PATCH, but it is **not a nested partial update**.
+Preserve `name`, `system_prompt`, `use_search`, the complete `unified_tools` list
+(including other tools, templates, auth and `draft_policy`), and the full desired
+contract map. Also preserve description, attachments, suggested questions,
+model settings, handoff and other writable settings. Sending one changed tool
+replaces the list; omitting a contract entry resets that input to ordinary string.
+GET responses and writable payloads have different shapes; reconstruct attachment
+IDs and other absent writable fields from current version evidence as needed.
+Do not apply an update if a current setting cannot be preserved by the CLI. See
+[the skill workflow](../codeer-agent/reference/http-input-contracts.md) for details.
+
+Dry-run's `http_inputs` lists tool indexes and each generated key's effective
+`type` / `format` / `json_type`, with `configured: false` for defaults. It excludes
+HTTP URLs, auth, headers, query values, instructions and template content.
+`body_inputs_used` is false for GET/HEAD, whose body inputs are unused at runtime.
+`--full` and `--out` deliberately retain complete nested content, including
+credentials; metadata cleanup is limited to resource-level account fields and
+workspace identity. These exports are not redacted artifacts.
+
+Compare the fresh GET and exact version snapshot with the intended tools and
+contracts; the server may materialize omitted defaults. `agent versions --out`
+exports version metadata, not snapshots; use `agent get --history` for a snapshot.
+Apply saves a draft. Publish the verified version separately, after approval,
+using `codeer agent publish --agent <agent-id> --history <history-id>` (preview
+with `--dry-run` first).
+
 ## Upgrade and uninstall
 
 Upgrade the CLI:
@@ -200,8 +298,9 @@ Use this pattern during agent lifecycle work:
 
 ```bash
 codeer agent list
-codeer history list --agent <agent-id> --limit 50
+codeer history list --agent <agent-id> --has-ai-drafts --limit 50
 codeer history conversations <history-id> --out .codeer/current/history-<history-id>.json
+codeer history ai-drafts <history-id> --out .codeer/current/ai-drafts-<history-id>.json
 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
@@ -220,19 +319,55 @@ workspace.
 
 Flags:
 
-- `--full` prints bounded extra detail for human inspection. It is still
-  intended to be safe for LLM context.
+- `--full` prints bounded extra detail for human inspection. Some commands,
+  including `agent get`, can expose configuration credentials; `history
+  ai-drafts` can expose sensitive conversation text and therefore requires
+  `--out`. Use each command's flag description as the output contract, and
+  inspect complete artifacts locally without flooding LLM context.
 - `--out <path>` writes complete diagnostic artifacts to a local file. Use it
   for raw eval results, full conversation turns, full rubric matrices, and
   other data that can grow with cases, versions, or turns.
 
-`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.
+`history conversations` reads `/api/v1/external/histories/{id}/messages`
+using a workspace admin API key and follows all pages automatically. Member
+keys retain existing History visibility but are intentionally rejected by this
+complete tool-payload export. This requires a server supporting
+`history-parts-v1`; it never falls back to a
+different authorization contract. Stdout shows at most 20 part summaries (50
+with `--full`) and omits tool payload previews. `--out` retains native tool
+args/results/outcomes, group/part IDs, attachments, feedback, and metadata.
+Attachment URLs remain permission-checked History download endpoints rather
+than direct storage/source URLs.
+Legacy projections have `source: legacy-adapter`; tool outcomes absent from
+the original records are omitted and marked `outcome_not_recorded`. System
+prompts and provider raw traces are not included. Missing parts do not prove a tool never ran. Keep export files private.
+
+`--client-visible --user <external-user-id>` explicitly selects the existing
+Chat V2 owner/allowlist contract. No external identity is inferred from History
+metadata. `history get` and the low-level legacy `get_conversations` reader
+remain compatible. Management exports do not hydrate display-only tool payloads.
+
+Release order: deploy the backend supporting `history-parts-v1` first, verify
+an authorized management export across multiple pages, then release/install
+this CLI. Existing CLI versions retain their previous behavior until upgraded.
+If the backend endpoint is unavailable, the new CLI fails explicitly with no
+fallback; keep the previous CLI installed until backend verification passes.
+The management endpoint can remain available if the CLI release is rolled back.
+
+`history list --has-ai-drafts` narrows the history page to conversations with
+at least one AI Draft and includes lifecycle counts in compact output.
+`history ai-drafts` follows every server page and writes every returned draft
+lifecycle record to `--out`: generated content, refinement lineage,
+`generation_instruction`, `dismiss_reason`, `dismiss_feedback`, outcomes, tool
+activities, proposed actions, operator attribution, and the correlated actual
+delivery when one exists. Default stdout shows structural flags and counts but
+no generated, operator, customer, or tool text. `--full --out <path>` explicitly
+opts into bounded content previews. The endpoint has no revision token, so a
+multi-page artifact is marked `snapshot_consistency: best-effort`: count changes
+and duplicate IDs fail the export, but lifecycle fields can still change during
+paging. Re-run when point-in-time consistency matters. These fields are evidence
+for an improvement analysis; the CLI does not invent a recommended Agent change
+from them.
 
 Use the external client-owner contract only when that distinction is the point
 of the test:

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

@@ -1,25 +1,26 @@
 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/_http_contracts.py,sha256=W1YSs9DhWCImDEloin47361qxFNBePuzZKnWRUb16CY,4612
+codeer_cli/_validate.py,sha256=7GEIwLzjP5fPthfsCNtsnqBYiFWqIbuOe_SltrHCE7Q,7302
+codeer_cli/agents.py,sha256=kCvCF7LHQrDOVR80x3i9sWTeC08qvCvR-aUDIMMx5xc,6399
 codeer_cli/chats.py,sha256=Vg1DIu8fT6mPyPpfqLpExKvXhdZEWCyJGPvalQy3BXg,7989
-codeer_cli/cli.py,sha256=PDi0WLC4prkFSbY0Y7619MAdP3uoDzgTWekHrhHprHc,4756
-codeer_cli/client.py,sha256=apUycjK-OvHEquAj58FqOy8FHmHjA6K9dScaYQ4M-VU,13175
+codeer_cli/cli.py,sha256=Y5f_HdCAd-gMKlgh49OO-T396f9o_BhpTOFI971NItk,4907
+codeer_cli/client.py,sha256=7fFDAMW5jliMx6PLFovfHDLOLj8z4Uyj5Nm_GdDAr8A,13266
 codeer_cli/constants.py,sha256=D1pV3wCoqYybrKGKeoupYjjFWLfaFviKp1yL7oh6Qso,2323
 codeer_cli/eval_.py,sha256=TjDFGCGF19JaUmSaP3PiKIRrBIvYaU-EJS4dC-N7eBI,17868
-codeer_cli/histories.py,sha256=Tom4tM20mls-Jo-q7NXish3zeOyMM5Nkd7MZjHFfy88,9979
+codeer_cli/histories.py,sha256=UvFGOMrWeQTh0CjGxBB7rNlRarJrp8kHJVwi9sT7FYI,14592
 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/_util.py,sha256=AM-ks4Q_HwMlACBEj8pNKqo7yWoOWuQZeHVehy9MwJQ,1915
+codeer_cli/commands/agent.py,sha256=vNPWMboU1pr6pD-8agfP9TjY_UThoJwGKIvshueanig,17471
 codeer_cli/commands/check.py,sha256=lTxolx1mIJ8jldPhJ5FXqie9nbCLVOO-sDPOHTSy1-w,3817
 codeer_cli/commands/eval_cmd.py,sha256=S-ydzWZppPLMCu2i_HOK0OW5ZaoebxcLO--WDYOIuAk,73548
-codeer_cli/commands/history.py,sha256=jUm0ZnIaJc0FV7pwMNdCBuuKPoauhDY2swFqB6_byWU,18800
+codeer_cli/commands/history.py,sha256=3VqyllZP2PvYvWbgw_GG2kK_VOFtkLndp_RIXuUBm3A,23166
 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.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,,
+codeer_cli-0.1.16.dist-info/METADATA,sha256=jYT-occxU9SDNf_CKXOzwJcaPXzC81_eDFVk4ujSFeU,18263
+codeer_cli-0.1.16.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+codeer_cli-0.1.16.dist-info/entry_points.txt,sha256=-nXIrlm5SR5r7gg3y8AS0tN66MwmvNHsrlwLNQNGD50,47
+codeer_cli-0.1.16.dist-info/RECORD,,

{codeer_cli-0.1.15.dist-info → codeer_cli-0.1.16.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.0
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any