xmemcli 0.0.7__tar.gz → 0.0.8__tar.gz

{xmemcli-0.0.7 → xmemcli-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xmemcli
-Version: 0.0.7
+Version: 0.0.8
 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.7**.
+Version: **0.0.8**.
 
 
 ---
@@ -167,7 +167,7 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.7` (see `xmemcli version`)
+**Version:** `0.0.8` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-governed for key acquisition**; an AI-assisted IDE may run reads, writes, and inventory once credentials exist. Humans acquire API keys and change quota limits in the **Console UI**.
 
@@ -211,6 +211,7 @@ Permission-filtered view of what this API key can see.
 |---------|-------------|
 | **`instance get`** `<instance_id>` | Fetch one instance |
 | **`instance create`** | Create from XMD/JSON schema. Required `--name`; schema via `--schema-file` or `--schema-stdin`. |
+| **`instance instructions`** `[instance_id]` `[text]` `[--clear]` | Read, set or clear the instance's standing instructions to an agent — the owner's own words, carried to every agent that connects it. No text and no `--clear` reads and changes nothing. Setting reads the current value first and writes with the epoch it read, so an edit composed against instructions someone has since replaced is refused rather than applied (the console form and the instance chat write the same field). Clearing is `--clear`; an empty string is refused, because that is what a shell substitutes for an unset variable. The id may be pinned with `--instance-id` or `$XMEM_INSTANCE_ID` and the text given alone — a lone positional that is not an id is read as the text. |
 | **`instance setup`** `[instance_id]` `[--format agent\|project]` | How to connect this instance to an agent, ordered for where it is likely to be used. Prints the same steps the `get_setup_instructions` MCP tool gives an agent, so a person and the agent beside them read the same thing. `--format project` additionally prints the shared setup files to commit; each teammate still approves the install and signs in once. Carries no credential. |
 
 ---

{xmemcli-0.0.7 → xmemcli-0.0.8}/README.md

@@ -89,7 +89,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.7**.
+Version: **0.0.8**.
 
 
 ---
@@ -159,7 +159,7 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.7` (see `xmemcli version`)
+**Version:** `0.0.8` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-governed for key acquisition**; an AI-assisted IDE may run reads, writes, and inventory once credentials exist. Humans acquire API keys and change quota limits in the **Console UI**.
 
@@ -203,6 +203,7 @@ Permission-filtered view of what this API key can see.
 |---------|-------------|
 | **`instance get`** `<instance_id>` | Fetch one instance |
 | **`instance create`** | Create from XMD/JSON schema. Required `--name`; schema via `--schema-file` or `--schema-stdin`. |
+| **`instance instructions`** `[instance_id]` `[text]` `[--clear]` | Read, set or clear the instance's standing instructions to an agent — the owner's own words, carried to every agent that connects it. No text and no `--clear` reads and changes nothing. Setting reads the current value first and writes with the epoch it read, so an edit composed against instructions someone has since replaced is refused rather than applied (the console form and the instance chat write the same field). Clearing is `--clear`; an empty string is refused, because that is what a shell substitutes for an unset variable. The id may be pinned with `--instance-id` or `$XMEM_INSTANCE_ID` and the text given alone — a lone positional that is not an id is read as the text. |
 | **`instance setup`** `[instance_id]` `[--format agent\|project]` | How to connect this instance to an agent, ordered for where it is likely to be used. Prints the same steps the `get_setup_instructions` MCP tool gives an agent, so a person and the agent beside them read the same thing. `--format project` additionally prints the shared setup files to commit; each teammate still approves the install and signs in once. Carries no credential. |
 
 ---

{xmemcli-0.0.7 → xmemcli-0.0.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xmemcli"
-version = "0.0.7"
+version = "0.0.8"
 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.7 → xmemcli-0.0.8}/uv.lock

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

{xmemcli-0.0.7 → xmemcli-0.0.8}/xmemcli/__init__.py

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

{xmemcli-0.0.7 → xmemcli-0.0.8}/xmemcli/_help.py

@@ -123,6 +123,7 @@ _OVERVIEW_SECTIONS: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = (
             ("instance get", "Get a single instance by id"),
             ("instance create", "Create a new instance from an XMD/JSON schema"),
             ("instance setup", "How to connect an instance to an agent"),
+            ("instance instructions", "Read, set or clear an instance's standing instructions to an agent"),
         ),
     ),
     (

{xmemcli-0.0.7 → xmemcli-0.0.8}/xmemcli/_instance_schema.py

@@ -8,6 +8,7 @@ import argparse
 import json
 import os
 import sys
+import uuid
 from pathlib import Path
 from typing import Any
 from urllib.parse import urlencode
@@ -80,6 +81,20 @@ def _resolve_instance_id(args: argparse.Namespace) -> str | None:
     return os.environ.get(m.ENV_INSTANCE_ID)
 
 
+def _looks_like_instance_id(value: str) -> bool:
+    """Whether this could be an instance id at all.
+
+    Used only to tell a misplaced argument from a real id — never to validate one the
+    server will check anyway. Deliberately permissive about formatting so a caller who
+    strips the dashes is not refused by their own client.
+    """
+    try:
+        uuid.UUID(value)
+    except ValueError:
+        return False
+    return True
+
+
 def _require_instance_id(args: argparse.Namespace) -> tuple[str | None, tuple[CliOutput, int] | None]:
     m = xmem_module()
     instance_id = _resolve_instance_id(args)
@@ -273,6 +288,128 @@ def cmd_instance_get(args: argparse.Namespace) -> tuple[CliOutput, int]:
     return (CliOutput(OutputKind.INSTANCE_GET, curate_instance(item, args.verbose)), m.EXIT_OK)
 
 
+def cmd_instance_instructions(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """Read, set or clear an instance's standing instructions to an agent.
+
+    The owner's own words, carried to every agent that connects this instance. Reading
+    is the default because that is the safe half: with no text and no ``--clear`` this
+    prints what is there and changes nothing.
+
+    **Setting reads first, then writes with the epoch it read.** The same field is
+    editable from the console's instance form and from the instance chat, so a write
+    composed against a value someone has since replaced is refused rather than applied.
+    Sending the text alone would make this the one editor that silently wins.
+
+    Clearing is ``--clear`` rather than an empty string. The API's rule is that an
+    explicit empty value clears and an omitted one is left alone, which is right for a
+    wire format and wrong for a terminal: `instructions <id> ""` is what a shell hands
+    over when a variable is unset, and that should not be how a standing rule is
+    deleted.
+    """
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    base = m._api_url(args).rstrip("/")
+    # Two optional positionals, and argparse fills the first one first — so with the
+    # instance pinned by --instance-id or the environment, `instructions "Prefer short
+    # answers."` lands the text in the id slot. Left alone that reads a nonsense instance
+    # and reports "not found", which looks like a failed lookup rather than what it is: a
+    # write that never happened.
+    #
+    # Reinterpreted rather than refused, because the documented form is
+    # `instructions [<id>] [text]` with the id optional, and refusing would have made the
+    # optional half unusable for writes — the reader would have to repeat an id they had
+    # already pinned. A lone positional that is not an id, when an id is available from
+    # elsewhere, is the text.
+    text: str | None = getattr(args, "text", None)
+    positional = getattr(args, "instance_id_arg", None)
+    if positional and text is None and not _looks_like_instance_id(positional):
+        fallback = getattr(args, "instance_id", None) or os.environ.get(m.ENV_INSTANCE_ID)
+        if not fallback:
+            return (
+                make_error(
+                    f"{positional!r} is not an instance id, and none is pinned. Pass the id first "
+                    "(`instance instructions <id> <text>`), or set --instance-id or "
+                    f"${m.ENV_INSTANCE_ID} and give the text alone",
+                    stage="usage",
+                ),
+                m.EXIT_USAGE,
+            )
+        text = positional
+        args.instance_id_arg = None
+
+    # The same resolution every instance-scoped command uses: positional, then
+    # --instance-id, then the environment.
+    instance_id, usage_error = _require_instance_id(args)
+    if usage_error is not None:
+        return usage_error
+
+    clearing: bool = bool(getattr(args, "clear", False))
+    if text is not None and clearing:
+        return (make_error("pass either replacement text or --clear, not both", stage="usage"), m.EXIT_USAGE)
+    if text is not None and not text.strip():
+        return (
+            make_error("refusing to clear from an empty string; use --clear to remove the instructions", stage="usage"),
+            m.EXIT_USAGE,
+        )
+
+    url = f"{base}/instances/{instance_id}"
+    try:
+        current = m._unwrap_items(m._get(url, api_key))
+    except m.ApiError as e:
+        if e.status == 404:
+            return (
+                make_error(f"instance {instance_id} not found or not visible to this key", status=404, stage="request"),
+                m.EXIT_HTTP_ERROR,
+            )
+        return http_error_output(e, context="request rejected")
+
+    if text is None and not clearing:
+        return (
+            CliOutput(
+                OutputKind.INSTANCE_INSTRUCTIONS,
+                {
+                    "instance_id": instance_id,
+                    "instructions": current.get("agent_owner_instructions"),
+                    "epoch": current.get("agent_owner_instructions_epoch", 0),
+                },
+            ),
+            m.EXIT_OK,
+        )
+
+    body = {
+        "agent_owner_instructions": "" if clearing else text,
+        # Read a moment ago, above. The server compares it under the row lock, so this
+        # closes the window a client-side "did it change?" check cannot.
+        "expected_owner_instructions_epoch": current.get("agent_owner_instructions_epoch", 0),
+    }
+    try:
+        updated = m._unwrap_items(m._patch(url, body, api_key))
+    except m.ApiError as e:
+        if e.status == 409:
+            return (
+                make_error(
+                    "the instructions changed while this command was composing its edit; "
+                    "read them again and reapply",
+                    status=409,
+                    stage="request",
+                ),
+                m.EXIT_HTTP_ERROR,
+            )
+        return http_error_output(e, context="update rejected")
+
+    return (
+        CliOutput(
+            OutputKind.INSTANCE_INSTRUCTIONS,
+            {
+                "instance_id": instance_id,
+                "instructions": updated.get("agent_owner_instructions"),
+                "epoch": updated.get("agent_owner_instructions_epoch", 0),
+            },
+        ),
+        m.EXIT_OK,
+    )
+
+
 def cmd_instance_setup(args: argparse.Namespace) -> tuple[CliOutput, int]:
     """Print how to connect an instance on an agent surface.
 

{xmemcli-0.0.7 → xmemcli-0.0.8}/xmemcli/_output.py

@@ -152,6 +152,12 @@ class OutputKind(StrEnum):
     #: agent surface. Commands only; never a credential.
     INSTANCE_SETUP = "instance_setup"
 
+    #: Output of ``xmemcli instance instructions`` — the instance's standing
+    #: instructions to an agent, read or after a write. Curated payload:
+    #: ``instance_id``, ``instructions`` (``None`` when none are set) and the
+    #: ``epoch`` the value was read at.
+    INSTANCE_INSTRUCTIONS = "instance_instructions"
+
     #: Output of ``xmemcli instance create``.
     INSTANCE_CREATE = "instance_create"
 

{xmemcli-0.0.7 → xmemcli-0.0.8}/xmemcli/_pretty.py

@@ -260,6 +260,30 @@ def _terminal_safe(value: object) -> str:
     return "".join(ch for ch in text if ch == "\t" or (ch.isprintable() and ch != "\x1b"))
 
 
+def _render_instance_instructions(payload: Any, stream: IO[str]) -> None:
+    """Print the standing instructions as text, not as a record.
+
+    A caller reading them almost always wants to pipe or read them, so the text is the
+    output and everything else is a header. Unset prints one line saying so rather than
+    nothing at all: silence and "the instructions are empty" are the same output
+    otherwise, and only one of them means the read worked.
+    """
+    if not isinstance(payload, dict):
+        _default_handler(payload, stream)
+        return
+    instructions = payload.get("instructions")
+    stream.write(f"instructions for {_terminal_safe(payload.get('instance_id', '?'))}\n")
+    if not (isinstance(instructions, str) and instructions.strip()):
+        stream.write("  (none set)\n")
+        return
+    # Split first, sanitize per line. `_terminal_safe` drops every unprintable character
+    # and a newline is one, so scrubbing the whole value first ran the lines together —
+    # and these are authoritative instructions, where joining two bullets or two policy
+    # boundaries changes what the reader is told.
+    for line in instructions.splitlines() or [""]:
+        stream.write(f"  {_terminal_safe(line)}\n")
+
+
 def _render_instance_setup(payload: Any, stream: IO[str]) -> None:
     """Print the connect instructions as instructions rather than as a payload.
 
@@ -684,6 +708,7 @@ _RENDERERS: dict[str, Renderer] = {
     "instance_create": _render_instance_create,
     "instance_delete": _render_instance_delete,
     "instance_setup": _render_instance_setup,
+    "instance_instructions": _render_instance_instructions,
     "schema_update": _render_xmd_schema,
     "schema_dry_run": _render_schema_dry_run,
     "schema_migrations": _render_schema_migrations,

{xmemcli-0.0.7 → xmemcli-0.0.8}/xmemcli/_version.py

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

{xmemcli-0.0.7 → xmemcli-0.0.8}/xmemcli/cli.py

@@ -104,6 +104,7 @@ from ._instance_schema import (  # noqa: E402  (sibling-script import)
     cmd_instance_create,
     cmd_instance_delete,
     cmd_instance_get,
+    cmd_instance_instructions,
     cmd_instance_setup,
     cmd_schema_dry_run,
     cmd_schema_get,
@@ -679,6 +680,17 @@ def _put(url: str, body: dict[str, Any], api_key: str, timeout_s: float = 60.0)
     return _read_json_response(_build_request(url, "PUT", api_key, body), timeout_s)
 
 
+def _patch(url: str, body: dict[str, Any], api_key: str, timeout_s: float = 60.0) -> dict[str, Any]:
+    """A partial update, where the *absence* of a field is the meaningful part.
+
+    Distinct from `_put` for the reason the API distinguishes them: a field this body
+    does not mention is left alone, and one it sets to an empty value is cleared. A
+    caller that sent the whole record back would wipe a standing instruction merely by
+    renaming an instance.
+    """
+    return _read_json_response(_build_request(url, "PATCH", api_key, body), timeout_s)
+
+
 def _delete(url: str, api_key: str, timeout_s: float = 60.0) -> dict[str, Any]:
     return _read_json_response(_build_request(url, "DELETE", api_key), timeout_s, allow_empty=True)
 
@@ -1787,6 +1799,30 @@ def _build_parser() -> argparse.ArgumentParser:
         help="'agent' (default) prints the steps to run now; 'project' also prints the shared setup files to commit; each teammate still approves and signs in once",
     )
     pis.set_defaults(func=cmd_instance_setup)
+    pii = pi_sub.add_parser(
+        "instructions",
+        help="Read, set or clear an instance's standing instructions to an agent",
+        add_help=False,
+    )
+    pii.add_argument(
+        "instance_id_arg",
+        metavar="instance_id",
+        nargs="?",
+        help="Instance to read or edit; defaults to --instance-id or $XMEM_INSTANCE_ID",
+    )
+    pii.add_argument(
+        "text",
+        nargs="?",
+        help="Replacement instructions. Omit to read; use --clear to remove them",
+    )
+    pii.add_argument(
+        "--clear",
+        action="store_true",
+        # Deleting a standing rule is its own flag rather than an empty string, which is
+        # what a shell substitutes for an unset variable.
+        help="Remove the instructions. Cannot be combined with replacement text",
+    )
+    pii.set_defaults(func=cmd_instance_instructions)
     pic = pi_sub.add_parser(
         "create",
         help="Create a new instance from an XMD/JSON schema",