codeer-cli 0.1.15__tar.gz → 0.1.16__tar.gz

{codeer_cli-0.1.15 → codeer_cli-0.1.16}/API_REFERENCE.md

@@ -9,7 +9,9 @@ endpoints authenticate via `x-api-key` from `CODEER_API_KEY`.
 
 Envelope: successful responses look like
 `{"error_code": 0, "message": "", "pagination": null, "data": <payload>}`.
-The client unwraps `data` automatically; errors raise `CodeerError`.
+The client unwraps `data` automatically; errors raise `CodeerError`. Reads that
+need top-level pagination can pass `unwrap=False` to preserve the validated
+success envelope.
 
 **Environment config split:**
 Auth means `CODEER_API_KEY`; it comes from the process environment only.
@@ -27,6 +29,11 @@ need a default agent.
 - `/histories` uses **`limit` + `offset`** (NOT `page` / `page_size`).
   Default in `histories.list()` is `limit=500`. Backend hard-cap may be
   lower — check the response length.
+- `/external/histories/{id}/ai-drafts` uses **`limit` + `offset`**, with
+  pagination in the response envelope. `histories.list_ai_drafts()` follows
+  every page and rejects total-count changes or duplicate IDs. It marks the
+  artifact `snapshot_consistency: best-effort` because the endpoint does not
+  expose a revision token.
 - `/api/v2/chats/{id}/messages` also uses `limit` + `offset`.
   `chats.list_messages()` follows pages until exhaustion; its `limit` argument
   is a page size, not a total-result cap.
@@ -290,8 +297,9 @@ the public CLI.
 | `POST /api/v2/chats` | Create a persisted history using an agent's current published version |
 | `POST /api/v2/chats/{id}/messages` | Append a turn through structured SSE using the current published version |
 | `GET /api/v1/external/histories/{id}/messages` | Export persisted diagnostic parts for workspace editors (`history-parts-v1`) |
+| `GET /api/v1/external/histories/{id}/ai-drafts` | Export AI Draft content, refinement signals, outcomes, tool activity, and actual delivery |
 | `GET /api/v2/chats/{id}/messages` | Read client-visible parts under the external client-owner contract |
-| `GET /api/v1/external/histories?agent_id=X&feedback_filter=improve_feedback&external_user_id=…` | List conversations with filters |
+| `GET /api/v1/external/histories?agent_id=X&feedback_filter=improve_feedback&external_user_id=…&has_ai_drafts=true` | List conversations with filters and AI Draft lifecycle counts |
 | `GET /api/v1/external/histories/{id}` | Read one history's metadata |
 | `GET /api/v1/external/histories/{id}/conversations` | Legacy compact conversation rows; not complete tool I/O |
 | `POST /api/v1/external/histories/{hid}/conversations/{cid}/feedbacks` | Leave freeform improvement feedback |
@@ -308,6 +316,18 @@ outcome, so read the history before retrying to avoid duplicate turns.
 V2 read contract explicitly. The management export includes persisted tool
 calls/results but excludes system prompts and provider raw traces.
 
+`codeer history ai-drafts <history-id> --out <path>` uses the AI Draft export
+and follows every page. The artifact preserves `generation_instruction`,
+`dismiss_feedback`, refinement ancestry, lifecycle outcome, tool activities,
+proposed actions, and correlated delivery. Those are recorded improvement
+signals, not a server-generated recommendation. Compare them with the History
+parts and accepted Behavior Contract before proposing an Agent change. Default
+stdout exposes only structural flags and counts; `--full --out <path>` opts into
+bounded sensitive text previews. Because this endpoint has no revision token,
+the artifact is marked `snapshot_consistency: best-effort`; total-count changes
+and duplicate IDs are rejected, but field updates during pagination cannot be
+detected.
+
 `feedback_filter` accepts the `FeedbackFilterType` enum values:
 `no_feedback`, `with_feedback`, `helpful_feedback`, `improve_feedback`.
 

{codeer_cli-0.1.15 → codeer_cli-0.1.16}/PKG-INFO

@@ -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 → codeer_cli-0.1.16}/README.md

@@ -157,6 +157,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:
@@ -182,8 +280,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
@@ -202,19 +301,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 → codeer_cli-0.1.16}/pyproject.toml

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

codeer_cli-0.1.16/src/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-0.1.15 → codeer_cli-0.1.16}/src/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-0.1.15 → codeer_cli-0.1.16}/src/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-0.1.15 → codeer_cli-0.1.16}/src/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-0.1.15 → codeer_cli-0.1.16}/src/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: