xmemcli 0.0.9__tar.gz → 0.0.10__tar.gz

{xmemcli-0.0.9 → xmemcli-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xmemcli
-Version: 0.0.9
+Version: 0.0.10
 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
@@ -97,7 +97,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.9**.
+Version: **0.0.10**.
 
 
 ---
@@ -191,7 +191,7 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.9` (see `xmemcli version`)
+**Version:** `0.0.10` (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.
 

{xmemcli-0.0.9 → xmemcli-0.0.10}/README.md

@@ -89,7 +89,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.9**.
+Version: **0.0.10**.
 
 
 ---
@@ -183,7 +183,7 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.9` (see `xmemcli version`)
+**Version:** `0.0.10` (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.
 

{xmemcli-0.0.9 → xmemcli-0.0.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xmemcli"
-version = "0.0.9"
+version = "0.0.10"
 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"

{xmemcli-0.0.9 → xmemcli-0.0.10}/uv.lock

@@ -4,5 +4,5 @@ requires-python = ">=3.12, <4"
 
 [[package]]
 name = "xmemcli"
-version = "0.0.9"
+version = "0.0.10"
 source = { editable = "." }

{xmemcli-0.0.9 → xmemcli-0.0.10}/xmemcli/__init__.py

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

{xmemcli-0.0.9 → xmemcli-0.0.10}/xmemcli/_context_cmd.py

@@ -94,6 +94,12 @@ _CONSUMER_HOOK_OUTPUT_LIMIT = 10_000
 #: just fits over the edge.
 MAX_PACK_CHARS = _CONSUMER_HOOK_OUTPUT_LIMIT - 500
 
+#: Sections the server renders per pack (identity, owner, rules, schema, live state).
+#: The footprint is a diagnostic, so a server sending more is not describing a pack this
+#: client received; publishing them unbounded would let a small response build a large
+#: document. Mirrors the renderer's section list rather than any transport limit.
+_MAX_SECTIONS_PER_PACK = 5
+
 
 def _requestable_ids(autoload: tuple[Any, ...], listed: AbstractSet[str]) -> tuple[list[str], list[str]]:
     """Ids the server will accept, and the ones dropped with a reason.
@@ -456,9 +462,94 @@ def _curated_unavailable(entry: Any) -> dict[str, Any]:
     return curated
 
 
+def _curated_pack(entry: Any) -> dict[str, Any]:
+    """One pack's footprint: what it cost, whether it was cut, and where the cost sits.
+
+    Sizes and identity only. The pack's own text is already in ``text``, and republishing
+    section bodies here would hand a caller a second copy of content that the clamp and
+    scrub below bound exactly once.
+
+    Section titles are the server's own headings rather than anything an owner wrote, but
+    they arrive over the wire like everything else here, so they are scrubbed and length-
+    bounded. Not the UTF-16 clamp the pack text also gets — a title is capped at 200 code
+    points, so it cannot reach the limit that clamp exists for. A count that is not a
+    number is published as ``None``: a caller doing arithmetic on it should see a gap, not
+    a zero it cannot distinguish from a section that genuinely cost nothing.
+    """
+    curated: dict[str, Any] = {
+        "instance_id": scrub(entry["instance_id"], limit=200) if isinstance(entry.get("instance_id"), str) else None,
+        "estimated_tokens": _count(entry.get("estimated_tokens")),
+        "truncated": entry["truncated"] if isinstance(entry.get("truncated"), bool) else None,
+    }
+    raw_sections = entry.get("sections")
+    # Filtered before the cap, not after: slicing first let junk consume the slots, so a
+    # response whose first five entries were nulls published none of the real ones.
+    sections = [s for s in raw_sections if isinstance(s, dict)] if isinstance(raw_sections, list) else []
+    # Bounded as well as filtered. The server renders at most five sections per pack, so
+    # anything beyond that is not a breakdown of anything, and an unbounded array on a
+    # payload whose text is hard-capped is a way for a small response to build a large
+    # document. Not the only one — ``unavailable`` above is still uncapped — but the cap
+    # is cheap where the shape is known.
+    curated["sections"] = [
+        {
+            "title": scrub(section["title"], limit=200) if isinstance(section.get("title"), str) else None,
+            "estimated_tokens": _count(section.get("estimated_tokens")),
+        }
+        for section in sections[:_MAX_SECTIONS_PER_PACK]
+    ]
+    return curated
+
+
+def _curated_universal_rules(entry: Any) -> dict[str, Any] | None:
+    """The response-level rules block's footprint, or ``None`` when the server sent none.
+
+    Published for the same reason the per-pack sections are: this is the one part of the response
+    that belongs to no pack, so a caller summing ``packs`` to account for ``estimated_tokens``
+    comes up short by exactly it. It used to be inside every pack and is now charged once, which
+    is a change someone reading the breakdown to explain a budget needs to see.
+
+    Title and size only, like ``_curated_pack`` — the body is already in ``text``.
+    """
+    if not isinstance(entry, dict):
+        return None
+    return {
+        "title": scrub(entry["title"], limit=200) if isinstance(entry.get("title"), str) else None,
+        "estimated_tokens": _count(entry.get("estimated_tokens")),
+    }
+
+
+def _count(value: Any) -> int | None:
+    """A published token count, or ``None`` when the server sent something that is not one.
+
+    ``bool`` is excluded explicitly because it is a subclass of ``int``: without that,
+    ``"estimated_tokens": true`` published ``true`` and a caller summing the sections
+    added one, which is the arithmetic the ``None`` exists to keep honest. Spelled the
+    same way in ``_pretty.py`` and ``xmem.py``; ``_binding.py`` reaches the same result
+    through the negated form. The idiom appears at several sites in ``cli/`` and each
+    checks something different afterwards (``> 0``, ``>= 0``, ``< 1``), which is why this
+    stays local rather than becoming a shared helper.
+    """
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
 def _nothing_to_inject() -> dict[str, Any]:
-    """The payload for "there is no context to add", used by every such path."""
-    return {"text": "", "instance_ids": [], "unavailable": [], "estimated_tokens": 0}
+    """The payload for "there is no context to add", used by every such path.
+
+    ``max_tokens`` is ``None`` rather than absent: the success path always carries it,
+    and a caller told the shape is stable should not have to test for the key before
+    reading it on the one branch that omitted it.
+    """
+    return {
+        "text": "",
+        "instance_ids": [],
+        "unavailable": [],
+        "estimated_tokens": 0,
+        "max_tokens": None,
+        "packs": [],
+        # Present and null for the same reason ``max_tokens`` is: the success path always carries
+        # the key, and a caller told the shape is stable should not have to test for it.
+        "universal_rules": None,
+    }
 
 
 def _command_budget(args: argparse.Namespace) -> float:
@@ -743,6 +834,23 @@ def _context(args: argparse.Namespace, deadline: float) -> tuple[CliOutput, int]
     # `diff_plan`, anything an internal renderer attaches) cannot arrive here and be
     # published; it is dropped until someone decides it belongs.
     unavailable = [_curated_unavailable(entry) for entry in unavailable]
+    # Shape-checked before iteration for the same reason `items` and `unavailable` above
+    # are: `result.get("packs") or []` keeps whatever truthy value arrived, so
+    # `{"packs": 7}` raised `TypeError` out of the comprehension and the blanket guard
+    # turned a perfectly good, already-clamped pack into an empty payload — the whole
+    # session's context discarded because an optional diagnostic field had the wrong
+    # type. A dict or a string would not even raise: they iterate, and publish phantom
+    # entries. The footprint is a diagnostic, so a bad one costs itself and nothing else.
+    raw_packs = result.get("packs")
+    if raw_packs is not None and not isinstance(raw_packs, list):
+        m._note_cli_warning(args, "xmemory returned an unreadable context footprint; sizes omitted")
+        raw_packs = []
+    # Non-dict elements are skipped rather than curated into all-null entries: a
+    # phantom pack is the outcome the guard above warns about, one level down, and a
+    # caller cannot tell it from an instance that genuinely reported nothing. Capped at
+    # the number of instances the server will accept in one request, for the same reason
+    # the sections are capped.
+    packs = [_curated_pack(p) for p in [p for p in (raw_packs or []) if isinstance(p, dict)][:MAX_REQUESTED_INSTANCES]]
     delivered = [i for i in requested if i not in missing]
     if unavailable:
         m._note_cli_warning(
@@ -769,7 +877,30 @@ def _context(args: argparse.Namespace, deadline: float) -> tuple[CliOutput, int]
     # passes the first at 9,500 and measures 19,000 to the second, and Claude Code
     # writes it to a file and injects a preview instead of the context. Bounding the
     # unit the consumer actually counts is what the cap was for.
-    text = clamp_utf16(scrub(text, limit=MAX_PACK_CHARS), limit=MAX_PACK_CHARS)
+    # Sanitised first, with a limit that cannot bite, so the two jobs `scrub` performs are
+    # separated: it strips Cc/Cf/Cs characters *and* clamps. Measuring the final text
+    # against the raw server text conflated them — a fully delivered pack carrying one
+    # zero-width joiner, soft hyphen, BOM or bidi mark came out shorter and was reported as
+    # cut, which is a false alarm aimed at exactly the reader who asked why their context
+    # shrank. Only a length cut is a length cut.
+    sanitised = scrub(text, limit=len(text))
+    injected = clamp_utf16(scrub(sanitised, limit=MAX_PACK_CHARS), limit=MAX_PACK_CHARS)
+    # The footprint below describes what the *server* rendered. When this clamp bites, part
+    # of that never reaches the model, and a breakdown still reporting the full sizes with
+    # `truncated: false` misleads precisely the reader it exists for — someone asking why
+    # their live state disappeared, being shown a section that advertises 4,900 tokens and
+    # arrived as nothing. So a client-side cut marks every pack too. The flag means "what
+    # you are reading is not the whole of it", whichever side did the cutting; the warning
+    # names which side, because the fixes are different — retier a binding, or lower
+    # `pack_max_tokens`.
+    if len(injected) < len(sanitised):
+        m._note_cli_warning(
+            args,
+            "the rendered context was longer than this client can inject and was cut; "
+            "the sizes reported describe what xmemory rendered, not what was injected",
+        )
+        packs = [{**pack, "truncated": True} for pack in packs]
+    text = injected
     return (
         CliOutput(
             OutputKind.AGENT_CONTEXT,
@@ -777,8 +908,22 @@ def _context(args: argparse.Namespace, deadline: float) -> tuple[CliOutput, int]
                 "text": text,
                 "instance_ids": delivered,
                 "unavailable": unavailable,
-                "estimated_tokens": result.get("estimated_tokens") or 0,
-                "max_tokens": result.get("max_tokens"),
+                # Through the same guard as the parts: publishing `true` as a total while
+                # the sections it explains correctly read null is the inconsistency the
+                # breakdown exists to avoid.
+                "estimated_tokens": _count(result.get("estimated_tokens")) or 0,
+                "max_tokens": _count(result.get("max_tokens")),
+                # Where the total sits, per instance and per section. The total alone says a
+                # pack was expensive or was cut; only the breakdown says which instance spent
+                # the budget and what a shrink took, which is what someone asking "why is my
+                # context so big" or "why did my live state disappear" is actually asking.
+                # Curated the way `unavailable` is, so a section body cannot arrive by this
+                # route and bypass the clamp the pack text goes through.
+                "packs": packs,
+                # The part of the total that belongs to no pack: the operating rules, carried once
+                # for the response rather than repeated in each pack. Without it the breakdown
+                # cannot account for its own total.
+                "universal_rules": _curated_universal_rules(result.get("universal_rules")),
             },
         ),
         m.EXIT_OK,

{xmemcli-0.0.9 → xmemcli-0.0.10}/xmemcli/_output.py

@@ -139,7 +139,18 @@ class OutputKind(StrEnum):
 
     #: Output of ``xmemcli context`` — the session-start pack for the autoload
     #: bindings in this directory. Curated payload: ``{text, instance_ids,
-    #: unavailable, estimated_tokens, max_tokens}``. ``text`` is injected verbatim.
+    #: unavailable, estimated_tokens, max_tokens, packs, universal_rules}``. ``text`` is injected
+    #: verbatim; ``packs`` is the footprint breakdown — per instance, and per
+    #: section within it — carrying sizes and titles but no section bodies.
+    #: The breakdown accounts for slightly less than ``estimated_tokens``, in both
+    #: directions: each pack's heading, the blank lines between packs and the note
+    #: prepended when a project binding introduced instances are injected text
+    #: charged to no section, and a pack too long for this client is cut after the
+    #: sizes are read — every ``truncated`` is then ``true`` and a warning says so.
+    #: Present the parts as where the budget went, not as an exact decomposition.
+    #: ``max_tokens`` is ``null`` whenever no pack was delivered — which includes
+    #: every failure path, so read ``warnings`` for why rather than inferring an
+    #: empty binding.
     AGENT_CONTEXT = "agent_context"
 
     #: Output of ``xmemcli org list instances`` (and ``instance list`` alias).

{xmemcli-0.0.9 → xmemcli-0.0.10}/xmemcli/_pretty.py

@@ -114,6 +114,18 @@ def _render_read_structured(payload: Any, stream: IO[str]) -> None:
     The curated payload IS the rows / xresponse the operator explicitly
     asked for; dump it as JSON.
     """
+    if isinstance(payload, dict) and payload.get("reader_result", ...) is None:
+        stream.write("No rows.\n")
+        pending = payload.get("pending_suggestions")
+        if isinstance(pending, int) and not isinstance(pending, bool) and pending > 0:
+            stream.write(f"({pending} pending schema suggestion(s) — {CLI_NAME} schema suggestions review)\n")
+        trace_id = payload.get("trace_id")
+        if isinstance(trace_id, str) and trace_id.strip():
+            stream.write(f"  trace: {_terminal_safe(trace_id.strip())}\n")
+        console_url = payload.get("console_url")
+        if isinstance(console_url, str) and console_url.strip():
+            stream.write(f"  console: {_terminal_safe(console_url.strip())}\n")
+        return
     json.dump(payload, stream, indent=2, default=str)
     stream.write("\n")
 

{xmemcli-0.0.9 → xmemcli-0.0.10}/xmemcli/_version.py

@@ -1,4 +1,4 @@
 """Release metadata for the xmemcli CLI (copied into standalone builds)."""
 
 CLI_NAME = "xmemcli"
-__version__ = "0.0.9"
+__version__ = "0.0.10"

{xmemcli-0.0.9 → xmemcli-0.0.10}/xmemcli/cli.py

@@ -776,7 +776,12 @@ def _curate_read(item: dict[str, Any], *, read_mode: str, verbose: bool) -> dict
     rr = item.get("reader_result")
     rr_dict = rr if isinstance(rr, dict) else {}
     curated: dict[str, Any]
-    if read_mode == "single":
+    if "reader_result" in item and rr is None:
+        # Preserve the server's explicit no-result signal. Converting None to
+        # an empty dict makes a zero-row read indistinguishable from an unknown
+        # or malformed ReaderResult shape.
+        curated = {"reader_result": None}
+    elif read_mode == "single":
         answer = _extract_single_answer(rr_dict)
         # No extractable answer string → emit the reader_result subtree so
         # the user still sees something truthful rather than `answer: null`.