xmemcli 1.3.0__tar.gz → 1.3.1__tar.gz

xmemcli-1.3.1/.gitignore

@@ -0,0 +1 @@
+.venv/

{xmemcli-1.3.0 → xmemcli-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xmemcli
-Version: 1.3.0
+Version: 1.3.1
 Summary: Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools.
 Keywords: api,cli,llm,memory,xmemory
 Requires-Python: <4,>=3.12
@@ -128,7 +128,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **1.3.0**.
+Version: **1.3.1**.
 
 
 ---
@@ -228,7 +228,7 @@ Each login binds its own port and names it in the login URL, so concurrent login
 
 # `xmemcli` — capabilities reference
 
-**Version:** `1.3.0` (see `xmemcli version`)
+**Version:** `1.3.1` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may initiate `auth login`, but a key is only issued after one explicit human approval — a click in the Console UI (PKCE handoff) or an approval of a sign-in email (`--email`). Quota limits change only in the **Console UI**. The full acquisition contract is in the auth-flow reference bundled with this package.
 
@@ -472,9 +472,9 @@ learn; the CLI composes the Console's search clauses itself.
 
 **Every operation row carries its internal ids.** `operations[]` rows have `operation_type`, `trace_id`, `instance_id`, `timestamp`, `status`, `is_success`, `error_code`, `session_id`, `user_id`, `user_email`, `api_key_id`, `api_key_name`, `api_key_prefix`, `time_taken_ms`, `text_snippet`, `object_names`, `field_names`.
 
-> **Three of those never resolve for an API key**, super admin or not, and this is by design rather than a gap. `user_email` is always absent: the accounts `/users` lookup is closed to keys (an agent may learn who *it* is, never enumerate the organisation's users), so rows keep `user_id` and you resolve names yourself if you need them — and a `User:<email>` search clause matches nothing; filter by `user_id`. `api_key_name` / `api_key_prefix` resolve only for the caller's **own** keys, because `GET /api-keys` scopes a key caller to its owner's keys. So a super admin's key does *not* see literally everything its owner's browser sees: it sees the same rows and the same fields, with those three enrichments empty. Everything scope-bearing — which instances, which detail fields, `llm_calls`, xuid substitution — is identical. Detail documents add what the Console's pane shows: `source_id`, `write_mode` / `read_mode`, `scope`, `extracted_objects`, `diff_plan` (sanitised unless super admin), `written_objects`, `migration_id`, `proposal_version`, `schema_version`, `stage`, `triggered_evolution {migration_id, evolution_trace_id, update_trace_id}`, and — **unrestricted callers only** (a super admin, or a browser session on a `KINGDOM_LOCAL` Console) — `llm_calls[]` (`llm_call_id`, `gateway_request_id`, `model_type`, `provider`, …), `full_error_message`, raw token counts, unsanitised xuids, `sql_queries`, `ddl_queries`, and `schema_generation`.
+> **Three of those never resolve for an API key**, super admin or not, and this is by design rather than a gap. `user_email` is always absent: the accounts `/users` lookup is closed to keys (an agent may learn who *it* is, never enumerate the organisation's users), so rows keep `user_id` and you resolve names yourself if you need them — and a `User:<email>` search clause matches nothing; filter by `user_id`. `api_key_name` / `api_key_prefix` resolve only for the caller's **own** keys, because `GET /api-keys` scopes a key caller to its owner's keys. So a super admin's key does *not* see literally everything its owner's browser sees: it sees the same rows and the same fields, with those three enrichments empty. Everything scope-bearing — which instances, which detail fields, `llm_calls`, xuid substitution — is identical. Detail documents add what the Console's pane shows: `source_id`, `write_mode` / `read_mode`, `scope`, `extracted_objects`, `diff_plan` (sanitised unless super admin), `written_objects`, `migration_id`, `proposal_version`, `schema_version`, `stage`, `triggered_evolution {migration_id, evolution_trace_id, update_trace_id}`, `sql_queries`, and — **unrestricted callers only** (a super admin, or a browser session on a `KINGDOM_LOCAL` Console) — `llm_calls[]` (`llm_call_id`, `gateway_request_id`, `model_type`, `provider`, …), `full_error_message`, raw token counts, unsanitised xuids, `ddl_queries`, and `schema_generation`.
 
-**A scoped key gets `[]` for `sql_queries` / `ddl_queries` / `schema_generation`, not the rows.** Those three come from `read_sql_queries`, `instance_create_ddl_queries` and `schema_generate_*`, which carry no instance ownership column — `schema_generate_*`'s trace id is client-supplied — so they cannot be scoped in SQL and are served only to callers with no instance restriction at all. This is a deliberate fail-closed choice, not a bug to work around: an empty array means "not available to this credential", never "this operation ran no SQL". `llm_calls[]` behaves the same way and always has. **Xuids are hidden for every non-super-admin**, including on writes that carry no identity map — the substitution is done by the Console, server-side, so a caller with no browser sees `#hidden` rather than a raw id.
+**A scoped key gets `[]` for `ddl_queries` / `schema_generation`, not the rows.** Those two come from `instance_create_ddl_queries` and `schema_generate_*`, which carry no instance ownership column — `schema_generate_*`'s trace id is client-supplied — so they cannot be scoped in SQL and are served only to callers with no instance restriction at all. This is a deliberate fail-closed choice, not a bug to work around: an empty array means "not available to this credential", never "this operation ran none". `llm_calls[]` behaves the same way and always has. `sql_queries` is not among them: `read_sql_queries` records the owning instance, so every caller who may open a read gets its SQL, attributed to that read even when another instance reused the trace id. **Xuids are hidden for every non-super-admin**, including on writes that carry no identity map — the substitution is done by the Console, server-side, so a caller with no browser sees `#hidden` rather than a raw id.
 
 **Who sees what — the Console decides; `auth status` tells you which view to expect.**
 
@@ -630,7 +630,7 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, `not
 
 **Envelope errors** (HTTP **200** with non-empty `errors[]`) are not HTTP 401/403; they typically exit **3** with `stage: "request"`. Two exceptions. `QUOTA_EXCEEDED` exits **6** with `stage: "quota"`, the same as it does on a real HTTP 402 — the keepalive flattening does not change the exit code — and this applies to every command that classifies the error, not just `write` and `read`. `WRITE_STILL_PROCESSING` exits **8** with `stage: "processing"` and is not a failure at all; unlike the quota rung this one is **`write`-only**, because its guidance is to poll `write-status`, which is meaningless for any other verb — elsewhere it falls through to **3**/`request`.
 
-> **Known bug.** Some subcommands in the `instance`, `schema` and `xmd` groups — `instance get`, `schema get` and `xmd generate` among them — unwrap the response outside their error handling, so an envelope error never reaches the classifier and escapes as an uncaught exception: a traceback and shell exit **1**, which is not in the table above. Those report **1**, not the **6** this section describes, until that is fixed. It is not whole groups: `instance instructions`, for example, reaches the classifier and exits **6** as documented.
+> **Known bug.** Some subcommands in the `instance` and `schema` groups — `instance get` and `schema get` among them — unwrap the response outside their error handling, so an envelope error never reaches the classifier and escapes as an uncaught exception: a traceback and shell exit **1**, which is not in the table above. Those report **1**, not the **6** this section describes, until that is fixed. It is not whole groups: `instance instructions`, for example, reaches the classifier and exits **6** as documented, and every heartbeat-wrapped command (`instance create`, `xmd generate`, `xmd enhance`, `schema update`, `schema dry-run`) unwraps inside its handler and exits **6**.
 
 **Breaking change in 0.0.5:** HTTP **403** previously exited **4** (`auth`); it now exits **3** (`permission`). Scripts that treated exit **4** as “any auth-layer failure” must check `stage` or handle exit **3** for permission denials.
 

{xmemcli-1.3.0 → xmemcli-1.3.1}/README.md

@@ -120,7 +120,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **1.3.0**.
+Version: **1.3.1**.
 
 
 ---
@@ -220,7 +220,7 @@ Each login binds its own port and names it in the login URL, so concurrent login
 
 # `xmemcli` — capabilities reference
 
-**Version:** `1.3.0` (see `xmemcli version`)
+**Version:** `1.3.1` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may initiate `auth login`, but a key is only issued after one explicit human approval — a click in the Console UI (PKCE handoff) or an approval of a sign-in email (`--email`). Quota limits change only in the **Console UI**. The full acquisition contract is in the auth-flow reference bundled with this package.
 
@@ -464,9 +464,9 @@ learn; the CLI composes the Console's search clauses itself.
 
 **Every operation row carries its internal ids.** `operations[]` rows have `operation_type`, `trace_id`, `instance_id`, `timestamp`, `status`, `is_success`, `error_code`, `session_id`, `user_id`, `user_email`, `api_key_id`, `api_key_name`, `api_key_prefix`, `time_taken_ms`, `text_snippet`, `object_names`, `field_names`.
 
-> **Three of those never resolve for an API key**, super admin or not, and this is by design rather than a gap. `user_email` is always absent: the accounts `/users` lookup is closed to keys (an agent may learn who *it* is, never enumerate the organisation's users), so rows keep `user_id` and you resolve names yourself if you need them — and a `User:<email>` search clause matches nothing; filter by `user_id`. `api_key_name` / `api_key_prefix` resolve only for the caller's **own** keys, because `GET /api-keys` scopes a key caller to its owner's keys. So a super admin's key does *not* see literally everything its owner's browser sees: it sees the same rows and the same fields, with those three enrichments empty. Everything scope-bearing — which instances, which detail fields, `llm_calls`, xuid substitution — is identical. Detail documents add what the Console's pane shows: `source_id`, `write_mode` / `read_mode`, `scope`, `extracted_objects`, `diff_plan` (sanitised unless super admin), `written_objects`, `migration_id`, `proposal_version`, `schema_version`, `stage`, `triggered_evolution {migration_id, evolution_trace_id, update_trace_id}`, and — **unrestricted callers only** (a super admin, or a browser session on a `KINGDOM_LOCAL` Console) — `llm_calls[]` (`llm_call_id`, `gateway_request_id`, `model_type`, `provider`, …), `full_error_message`, raw token counts, unsanitised xuids, `sql_queries`, `ddl_queries`, and `schema_generation`.
+> **Three of those never resolve for an API key**, super admin or not, and this is by design rather than a gap. `user_email` is always absent: the accounts `/users` lookup is closed to keys (an agent may learn who *it* is, never enumerate the organisation's users), so rows keep `user_id` and you resolve names yourself if you need them — and a `User:<email>` search clause matches nothing; filter by `user_id`. `api_key_name` / `api_key_prefix` resolve only for the caller's **own** keys, because `GET /api-keys` scopes a key caller to its owner's keys. So a super admin's key does *not* see literally everything its owner's browser sees: it sees the same rows and the same fields, with those three enrichments empty. Everything scope-bearing — which instances, which detail fields, `llm_calls`, xuid substitution — is identical. Detail documents add what the Console's pane shows: `source_id`, `write_mode` / `read_mode`, `scope`, `extracted_objects`, `diff_plan` (sanitised unless super admin), `written_objects`, `migration_id`, `proposal_version`, `schema_version`, `stage`, `triggered_evolution {migration_id, evolution_trace_id, update_trace_id}`, `sql_queries`, and — **unrestricted callers only** (a super admin, or a browser session on a `KINGDOM_LOCAL` Console) — `llm_calls[]` (`llm_call_id`, `gateway_request_id`, `model_type`, `provider`, …), `full_error_message`, raw token counts, unsanitised xuids, `ddl_queries`, and `schema_generation`.
 
-**A scoped key gets `[]` for `sql_queries` / `ddl_queries` / `schema_generation`, not the rows.** Those three come from `read_sql_queries`, `instance_create_ddl_queries` and `schema_generate_*`, which carry no instance ownership column — `schema_generate_*`'s trace id is client-supplied — so they cannot be scoped in SQL and are served only to callers with no instance restriction at all. This is a deliberate fail-closed choice, not a bug to work around: an empty array means "not available to this credential", never "this operation ran no SQL". `llm_calls[]` behaves the same way and always has. **Xuids are hidden for every non-super-admin**, including on writes that carry no identity map — the substitution is done by the Console, server-side, so a caller with no browser sees `#hidden` rather than a raw id.
+**A scoped key gets `[]` for `ddl_queries` / `schema_generation`, not the rows.** Those two come from `instance_create_ddl_queries` and `schema_generate_*`, which carry no instance ownership column — `schema_generate_*`'s trace id is client-supplied — so they cannot be scoped in SQL and are served only to callers with no instance restriction at all. This is a deliberate fail-closed choice, not a bug to work around: an empty array means "not available to this credential", never "this operation ran none". `llm_calls[]` behaves the same way and always has. `sql_queries` is not among them: `read_sql_queries` records the owning instance, so every caller who may open a read gets its SQL, attributed to that read even when another instance reused the trace id. **Xuids are hidden for every non-super-admin**, including on writes that carry no identity map — the substitution is done by the Console, server-side, so a caller with no browser sees `#hidden` rather than a raw id.
 
 **Who sees what — the Console decides; `auth status` tells you which view to expect.**
 
@@ -622,7 +622,7 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, `not
 
 **Envelope errors** (HTTP **200** with non-empty `errors[]`) are not HTTP 401/403; they typically exit **3** with `stage: "request"`. Two exceptions. `QUOTA_EXCEEDED` exits **6** with `stage: "quota"`, the same as it does on a real HTTP 402 — the keepalive flattening does not change the exit code — and this applies to every command that classifies the error, not just `write` and `read`. `WRITE_STILL_PROCESSING` exits **8** with `stage: "processing"` and is not a failure at all; unlike the quota rung this one is **`write`-only**, because its guidance is to poll `write-status`, which is meaningless for any other verb — elsewhere it falls through to **3**/`request`.
 
-> **Known bug.** Some subcommands in the `instance`, `schema` and `xmd` groups — `instance get`, `schema get` and `xmd generate` among them — unwrap the response outside their error handling, so an envelope error never reaches the classifier and escapes as an uncaught exception: a traceback and shell exit **1**, which is not in the table above. Those report **1**, not the **6** this section describes, until that is fixed. It is not whole groups: `instance instructions`, for example, reaches the classifier and exits **6** as documented.
+> **Known bug.** Some subcommands in the `instance` and `schema` groups — `instance get` and `schema get` among them — unwrap the response outside their error handling, so an envelope error never reaches the classifier and escapes as an uncaught exception: a traceback and shell exit **1**, which is not in the table above. Those report **1**, not the **6** this section describes, until that is fixed. It is not whole groups: `instance instructions`, for example, reaches the classifier and exits **6** as documented, and every heartbeat-wrapped command (`instance create`, `xmd generate`, `xmd enhance`, `schema update`, `schema dry-run`) unwraps inside its handler and exits **6**.
 
 **Breaking change in 0.0.5:** HTTP **403** previously exited **4** (`auth`); it now exits **3** (`permission`). Scripts that treated exit **4** as “any auth-layer failure” must check `stage` or handle exit **3** for permission denials.
 

xmemcli-1.3.1/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "xmemcli"
+version = "1.3.1"
+description = "Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools."
+readme = "README.md"
+requires-python = ">=3.12,<4"
+dependencies = []
+keywords = ["xmemory", "cli", "api", "memory", "llm"]
+
+[project.scripts]
+xmemcli = "xmemcli.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["xmemcli"]
+
+# The sdist names what it carries rather than what it excludes. Hatchling otherwise ships every
+# file in the staging tree, which is how the smoke run's uv.lock reached PyPI in 1.3.0. The one
+# file this list does not govern is .gitignore: hatchling force-includes the nearest one it finds
+# walking up from the project root until a .git entry, so an sdist always carries one. The
+# staging therefore writes its own, one line, or the archive would carry the monorepo's instead.
+[tool.hatch.build.targets.sdist]
+only-include = ["xmemcli", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

{xmemcli-1.3.0 → xmemcli-1.3.1}/xmemcli/__init__.py

@@ -1,3 +1,3 @@
 """Standalone xmemcli package (``xmemcli`` console script)."""
 
-__version__ = "1.3.0"
+__version__ = "1.3.1"

{xmemcli-1.3.0 → xmemcli-1.3.1}/xmemcli/_instance_schema.py

@@ -23,6 +23,23 @@ try:
 except ImportError:
     _yaml = None
 
+# ``generate_schema`` is a long-running LLM call bounded server-side by ``execution.api_timeout``.
+# That key is not one number: the code default and every deployment config say 900.0, while
+# ``config.yml.template`` says 1200.0. This is the largest checked-in bound plus slack for a
+# heartbeat-buffered response to arrive after the server's own deadline fires. Revisit when a
+# deployment sets ``api_timeout`` above 1200.0.
+#
+# It is an idle bound, not a whole-call deadline: ``urlopen`` applies the timeout to each socket
+# operation, and the server streams a heartbeat chunk every ``keepalive_interval_s`` once the
+# grace period passes, so a healthy call never approaches it however long it runs. What it does
+# guard is a proxy that buffers the whitespace chunks — then no bytes arrive until the body does,
+# and a value below the server's deadline would be what aborts the call.
+#
+# Named for the endpoint, not for one command: `xmd generate` and `xmd enhance` both POST to it and
+# are bounded by the same server deadline, so a bound that fitted only one of them would leave the
+# other aborting early against the very same call.
+_GENERATE_SCHEMA_TIMEOUT_S = 1260.0
+
 
 def _yaml_dump_or_json(value: Any) -> str:
     if _yaml is not None:
@@ -196,19 +213,90 @@ def _parse_schema_mutation_error_body(body: str) -> tuple[str, str, dict[str, An
     return "", body, {}
 
 
+#: Every ``details`` list a schema-mutation 422 may carry that already names the individual
+#: object/field/relation it is about. ``non_additive_changes``, ``uncovered_non_additive``, and
+#: ``destructive_ops`` are ``NonAdditiveChange`` / ``DestructiveOpSummary`` dumps; ``missing_additive_ops``
+#: and ``uncovered_additive_ops`` are ``MigrationOp`` dumps instead (see ``xmmodel.additive_plan_synthesizer``
+#: and ``api.schema_helpers``).
+_REJECTED_ELEMENT_DETAIL_KEYS = (
+    "non_additive_changes",
+    "uncovered_non_additive",
+    "uncovered_additive_ops",
+    "missing_additive_ops",
+    "destructive_ops",
+)
+
+
+def _rejected_elements(details: dict[str, Any]) -> list[dict[str, Any]]:
+    """Collect which object/field/relation each rejected element names, from ``details``.
+
+    Every list under `_REJECTED_ELEMENT_DETAIL_KEYS` the server may populate already carries
+    an identity for the thing it is about (``target``, or an ``object_name``/``field_name``/
+    ``name`` pair) plus a kind and a reason string; this only keeps the fields already present,
+    it never derives or invents one. Returns ``[]`` when ``details`` carries none of them, so a
+    rejection with no per-element detail stays without a fabricated ``elements`` list.
+    """
+    identity_fields = ("target", "name", "object_name", "field_name", "old_name", "new_name")
+    elements: list[dict[str, Any]] = []
+    for detail_key in _REJECTED_ELEMENT_DETAIL_KEYS:
+        items = details.get(detail_key)
+        if not isinstance(items, list):
+            continue
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            element: dict[str, Any] = {"detail": detail_key}
+            for field in identity_fields:
+                if item.get(field) is not None:
+                    element[field] = item[field]
+            kind = item.get("kind") or item.get("op_type")
+            if kind is not None:
+                element["kind"] = kind
+            reason = item.get("message") or item.get("reason")
+            if reason is not None:
+                element["reason"] = reason
+            elements.append(element)
+    return elements
+
+
+def _schema_mutation_error(message: str, *, status: int, stage: str, elements: list[dict[str, Any]]) -> CliOutput:
+    """Build the ``OutputKind.ERROR`` payload for a rejected schema mutation.
+
+    Same shape as `make_error` plus an ``elements`` key (only when non-empty) naming which
+    object/field/relation the server rejected, so a mixed edit does not just say "rejected".
+    """
+    payload: dict[str, Any] = {"error": message, "status": status, "stage": stage}
+    if elements:
+        payload["elements"] = elements
+    return CliOutput(OutputKind.ERROR, payload)
+
+
 def _handle_schema_mutation_error(e: HttpStatusError, *, instance_id: str) -> tuple[CliOutput, int]:
     m = xmem_module()
-    if e.status == 422:
-        error_type, msg, details = _parse_schema_mutation_error_body(e.body)
+    if e.status == 404:
+        return (
+            make_error(f"instance {instance_id} not found", status=e.status, stage="request"),
+            m.EXIT_HTTP_ERROR,
+        )
+    error_type, msg, details = _parse_schema_mutation_error_body(e.body)
+    # Every schema-mutation rejection carries the same structured ``SchemaHelperErrorPayload``;
+    # only the HTTP status varies with ``error_type`` (422 for validation, 409 for
+    # ``destructive_confirmation_required`` and the other preconditions — see
+    # ``_SCHEMA_APPLY_ERROR_STATUS`` in api/accounts/instances.py — and 200 when the rejection was
+    # streamed past the keepalive grace period). Dispatch on the body, so the stage and the
+    # ``elements`` it names survive whatever status carried it.
+    if error_type or e.status == 422:
         code = error_type.lower()
+        elements = _rejected_elements(details)
 
         if code == "non_additive_change_requires_plan":
             return (
-                make_error(
+                _schema_mutation_error(
                     f"non-additive change requires --migration-plan "
                     f"(produce one with `{m.CLI_NAME} xmd enhance --plan-output`)",
                     status=e.status,
                     stage="plan_required",
+                    elements=elements,
                 ),
                 m.EXIT_HTTP_ERROR,
             )
@@ -220,15 +308,16 @@ def _handle_schema_mutation_error(e: HttpStatusError, *, instance_id: str) -> tu
                     detail_bits.append(f"{key}={len(items)}")
             suffix = f" ({', '.join(detail_bits)})" if detail_bits else ""
             return (
-                make_error(f"{msg}{suffix}", status=e.status, stage="validate"),
+                _schema_mutation_error(f"{msg}{suffix}", status=e.status, stage="validate", elements=elements),
                 m.EXIT_HTTP_ERROR,
             )
         if code == "destructive_confirmation_required" or ("destructive" in code and "confirmation" in code):
             return (
-                make_error(
+                _schema_mutation_error(
                     "destructive change requires --confirm-destructive",
                     status=e.status,
                     stage="destructive",
+                    elements=elements,
                 ),
                 m.EXIT_HTTP_ERROR,
             )
@@ -237,32 +326,49 @@ def _handle_schema_mutation_error(e: HttpStatusError, *, instance_id: str) -> tu
             not error_type and "non_additive_change_requires" in msg.lower()
         ):
             return (
-                make_error(
+                _schema_mutation_error(
                     f"non-additive change requires --migration-plan "
                     f"(produce one with `{m.CLI_NAME} xmd enhance --plan-output`)",
                     status=e.status,
                     stage="plan_required",
+                    elements=elements,
                 ),
                 m.EXIT_HTTP_ERROR,
             )
         if "destructive" in code or (not error_type and "destructive" in msg.lower()):
             return (
-                make_error(
+                _schema_mutation_error(
                     "destructive change requires --confirm-destructive",
                     status=e.status,
                     stage="destructive",
+                    elements=elements,
                 ),
                 m.EXIT_HTTP_ERROR,
             )
-        return (make_error(msg, status=e.status, stage="validate"), m.EXIT_HTTP_ERROR)
-    if e.status == 404:
+        stage = "validate" if e.status == 422 else "request"
         return (
-            make_error(f"instance {instance_id} not found", status=e.status, stage="request"),
+            _schema_mutation_error(msg, status=e.status, stage=stage, elements=elements),
             m.EXIT_HTTP_ERROR,
         )
     return http_error_output(e, context="schema mutation rejected")
 
 
+def _streamed_rejection(item: dict[str, Any]) -> Any | None:
+    """The ``ApiError`` a rejection streamed under HTTP 200 stands for, or ``None`` for a result.
+
+    ``_schema_apply_error_response`` answers a rejected mutation with the bare
+    ``SchemaHelperErrorPayload`` — ``status: "error"``, ``error_type``, ``error_message``,
+    ``details`` — and its 409/422 reaches the wire only on the fast path. A mutation that outlives
+    the server's keepalive grace period comes back as HTTP 200 with that same payload as the body:
+    there is no ``errors`` array for ``_unwrap_items`` to reject, so it returns the payload as if it
+    were the result. A result is ``status: "ok"`` and never carries ``error_type``.
+    """
+    if item.get("status") != "error" or not item.get("error_type"):
+        return None
+    m = xmem_module()
+    return m.ApiError(200, json.dumps(item), str(item.get("error_message") or item["error_type"]))
+
+
 # The accepted values, duplicated here on purpose: this package is self-contained and
 # published on its own, so it cannot import the server's SetupFormat. A server-side test
 # asserts this tuple equals that enum, so the duplication cannot drift silently.
@@ -417,8 +523,7 @@ def cmd_instance_instructions(args: argparse.Namespace) -> tuple[CliOutput, int]
         if e.status == 409:
             return (
                 make_error(
-                    "the instructions changed while this command was composing its edit; "
-                    "read them again and reapply",
+                    "the instructions changed while this command was composing its edit; read them again and reapply",
                     status=409,
                     stage="request",
                 ),
@@ -702,6 +807,10 @@ def cmd_instance_create(args: argparse.Namespace) -> tuple[CliOutput, int]:
             api_key,
             timeout_s=180.0,
         )
+        # Unwrapped inside the handler: a provision that outlives the server's keepalive grace
+        # period comes back as HTTP 200 with the failure in the envelope's `errors` array, which
+        # `_unwrap_items` raises as ApiError, and nothing above this command catches one.
+        item = m._unwrap_items(envelope)
     except m.ApiError as e:
         if e.status == 403:
             limit = _extract_limit_message(e.body)
@@ -719,8 +828,7 @@ def cmd_instance_create(args: argparse.Namespace) -> tuple[CliOutput, int]:
             # a schema problem the list cannot help with.
             return (
                 make_error(
-                    f"instance create rejected: {e}; "
-                    f"list valid template ids with `{CLI_NAME} instance templates`",
+                    f"instance create rejected: {e}; list valid template ids with `{CLI_NAME} instance templates`",
                     status=e.status,
                     stage="request",
                 ),
@@ -728,7 +836,6 @@ def cmd_instance_create(args: argparse.Namespace) -> tuple[CliOutput, int]:
             )
         return http_error_output(e, context="instance create rejected")
 
-    item = m._unwrap_items(envelope)
     curated: dict[str, Any] = {
         "instance_id": item.get("id"),
         "name": item.get("name"),
@@ -770,11 +877,15 @@ def cmd_xmd_generate(args: argparse.Namespace) -> tuple[CliOutput, int]:
             f"{base}/clusters/{cluster_id}/instances/generate_schema",
             payload,
             api_key,
-            timeout_s=120.0,
+            timeout_s=_GENERATE_SCHEMA_TIMEOUT_S,
         )
+        # Unwrapped inside the handler, as in ``cmd_xmd_enhance``: a generation that outlives the
+        # server's keepalive grace period comes back as HTTP 200 with the failure in the envelope's
+        # `errors` array, which `_unwrap_items` raises as ApiError, and nothing above this command
+        # catches one.
+        item = m._unwrap_items(envelope)
     except m.ApiError as e:
         return http_error_output(e, context="request rejected")
-    item = m._unwrap_items(envelope)
     schema = item.get("data_schema") if isinstance(item, dict) else None
     if args.output and schema is not None:
         write_err = _write_text_file(args.output, _yaml_dump_or_json(schema), stage="generate")
@@ -808,6 +919,9 @@ def cmd_xmd_enhance(args: argparse.Namespace) -> tuple[CliOutput, int]:
             return (make_error("instance id required", stage="usage"), m.EXIT_USAGE)
         try:
             envelope = m._get(f"{base}/instances/{instance_id}/schema", api_key)
+            # Unwrapped inside the handler: an HTTP 200 whose envelope carries `errors` raises
+            # ApiError too, and nothing above this command catches one.
+            item = m._unwrap_items(envelope)
         except m.ApiError as e:
             if e.status == 404:
                 return (
@@ -815,7 +929,6 @@ def cmd_xmd_enhance(args: argparse.Namespace) -> tuple[CliOutput, int]:
                     m.EXIT_HTTP_ERROR,
                 )
             return http_error_output(e, context="schema get rejected")
-        item = m._unwrap_items(envelope)
         schema = item.get("data_schema") if isinstance(item, dict) else None
         if schema is None:
             return (make_error("instance has no live schema to enhance", stage="usage"), m.EXIT_USAGE)
@@ -841,11 +954,15 @@ def cmd_xmd_enhance(args: argparse.Namespace) -> tuple[CliOutput, int]:
             f"{base}/clusters/{cluster_id}/instances/generate_schema",
             payload,
             api_key,
-            timeout_s=120.0,
+            timeout_s=_GENERATE_SCHEMA_TIMEOUT_S,
         )
+        # Unwrapped inside the handler. An enhancement long enough to outlive the server's
+        # keepalive grace period comes back as HTTP 200 with the failure in the envelope's
+        # `errors` array, which `_unwrap_items` raises as ApiError — the shape a large-schema
+        # failure actually takes, and the one this command exists to report.
+        item = m._unwrap_items(envelope)
     except m.ApiError as e:
         return http_error_output(e, context="request rejected")
-    item = m._unwrap_items(envelope)
     if args.output and isinstance(item, dict) and item.get("data_schema") is not None:
         write_err = _write_text_file(args.output, _yaml_dump_or_json(item["data_schema"]), stage="enhance")
         if write_err is not None:
@@ -1004,9 +1121,17 @@ def cmd_schema_update(args: argparse.Namespace) -> tuple[CliOutput, int]:
             api_key,
             timeout_s=300.0,
         )
+        # Unwrapped inside the handler: a failure raised past the server's keepalive grace period
+        # comes back as HTTP 200 with an `errors` array, which `_unwrap_items` raises as ApiError;
+        # a *rejection* past it comes back as HTTP 200 with the bare rejection payload as the body,
+        # which `_streamed_rejection` recognises. Either way `_handle_schema_mutation_error` turns
+        # it into a JSON error document with a non-zero exit, not a success document or a traceback.
+        item = m._unwrap_items(envelope)
+        rejection = _streamed_rejection(item)
+        if rejection is not None:
+            raise rejection
     except m.ApiError as e:
         return _handle_schema_mutation_error(e, instance_id=instance_id)
-    item = m._unwrap_items(envelope)
     return (CliOutput(OutputKind.SCHEMA_UPDATE, item), m.EXIT_OK)
 
 
@@ -1031,9 +1156,15 @@ def cmd_schema_dry_run(args: argparse.Namespace) -> tuple[CliOutput, int]:
             api_key,
             timeout_s=120.0,
         )
+        # Unwrapped inside the handler, same reasoning as `cmd_schema_update`: this endpoint is
+        # heartbeat-wrapped too, so both 200 shapes past the grace period — a raised failure in
+        # `errors`, a rejection payload as the body — must land on `_handle_schema_mutation_error`.
+        item = m._unwrap_items(envelope)
+        rejection = _streamed_rejection(item)
+        if rejection is not None:
+            raise rejection
     except m.ApiError as e:
         return _handle_schema_mutation_error(e, instance_id=instance_id)
-    item = m._unwrap_items(envelope)
     return (CliOutput(OutputKind.SCHEMA_DRY_RUN, item), m.EXIT_OK)
 
 

{xmemcli-1.3.0 → xmemcli-1.3.1}/xmemcli/_version.py

@@ -4,7 +4,7 @@ import platform
 import re
 
 CLI_NAME = "xmemcli"
-__version__ = "1.3.0"
+__version__ = "1.3.1"
 
 # The header this CLI sends its identity in, restated rather than imported: the published package is
 # standalone and must not import anything outside this directory. The server's own constant is the other

xmemcli-1.3.0/.gitignore

@@ -1,4 +0,0 @@
-.venv/
-__pycache__/
-*.egg-info/
-.dist/

xmemcli-1.3.0/pyproject.toml

@@ -1,22 +0,0 @@
-[project]
-name = "xmemcli"
-version = "1.3.0"
-description = "Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools."
-readme = "README.md"
-requires-python = ">=3.12,<4"
-dependencies = []
-keywords = ["xmemory", "cli", "api", "memory", "llm"]
-
-[project.scripts]
-xmemcli = "xmemcli.cli:main"
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build.targets.wheel]
-packages = ["xmemcli"]
-
-[tool.pytest.ini_options]
-pythonpath = ["."]
-testpaths = ["tests"]

xmemcli-1.3.0/uv.lock

@@ -1,8 +0,0 @@
-version = 1
-revision = 3
-requires-python = ">=3.12, <4"
-
-[[package]]
-name = "xmemcli"
-version = "1.3.0"
-source = { editable = "." }