unique-sdk 2026.44.0.dev12__tar.gz → 2026.44.0.dev14__tar.gz

{unique_sdk-2026.44.0.dev12 → unique_sdk-2026.44.0.dev14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.44.0.dev12
+Version: 2026.44.0.dev14
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.44.0.dev12 → unique_sdk-2026.44.0.dev14}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.44.0.dev12"
+version = "2026.44.0.dev14"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.44.0.dev12 → unique_sdk-2026.44.0.dev14}/unique_sdk/cli/cli.py

@@ -69,7 +69,13 @@ from unique_sdk.cli.commands.mcp import cmd_mcp
 from unique_sdk.cli.commands.mcp import (
     is_error_output as _is_mcp_error_output,
 )
-from unique_sdk.cli.commands.navigation import cmd_cd, cmd_ls, cmd_pwd
+from unique_sdk.cli.commands.navigation import (
+    LS_DEFAULT_LIMIT,
+    LS_MAX_LIMIT,
+    cmd_cd,
+    cmd_ls,
+    cmd_pwd,
+)
 from unique_sdk.cli.commands.navigation import (
     is_ls_error_output as _is_ls_error_output,
 )
@@ -309,13 +315,44 @@ def cd(ctx: click.Context, target: str) -> None:
 
 @main.command()
 @click.argument("target", required=False, default=None)
+@click.option(
+    "--limit",
+    "-l",
+    type=int,
+    default=LS_DEFAULT_LIMIT,
+    show_default=True,
+    help=f"Max folders and max files to show (1-{LS_MAX_LIMIT}).",
+)
+@click.option(
+    "--skip",
+    type=int,
+    default=0,
+    show_default=True,
+    help="Skip this many folders and files first (for paging).",
+)
+@click.option(
+    "--all",
+    "-a",
+    "all_items",
+    is_flag=True,
+    help=f"Show up to {LS_MAX_LIMIT} folders and {LS_MAX_LIMIT} files.",
+)
 @click.pass_context
-def ls(ctx: click.Context, target: str | None) -> None:
+def ls(
+    ctx: click.Context,
+    target: str | None,
+    limit: int,
+    skip: int,
+    all_items: bool,
+) -> None:
     """List folders and files in a directory.
 
     \b
     Without TARGET, lists the current directory. With TARGET, lists
     the specified folder (by name, absolute path, or scope ID).
+    Shows 50 folders and 50 files by default. When a folder holds more,
+    the output says "showing ... of N" and prints the command for the
+    rest: use --skip to page, --limit to show more, or --all.
 
     \b
     Output columns: TYPE  NAME  ID  SIZE  UPDATED
@@ -327,8 +364,12 @@ def ls(ctx: click.Context, target: str | None) -> None:
       unique-cli ls              List root folders
       unique-cli ls /Reports     List a specific path
       unique-cli ls scope_abc    List by scope ID
+      unique-cli ls /Reports --skip 50    Next page of a large folder
+      unique-cli ls /Reports --all        Up to 1000 folders and files
     """
-    output = cmd_ls(LazyState.get(ctx), target)
+    output = cmd_ls(
+        LazyState.get(ctx), target, skip=skip, limit=limit, all_items=all_items
+    )
     emit(output, is_error=_is_ls_error_output)
 
 

{unique_sdk-2026.44.0.dev12 → unique_sdk-2026.44.0.dev14}/unique_sdk/cli/commands/files.py

@@ -11,6 +11,7 @@ from typing import Any
 
 import unique_sdk
 from unique_sdk.cli.formatting import format_content_info
+from unique_sdk.cli.metadata_filter import direct_children_filter
 from unique_sdk.cli.paths import canonical_folder_path, same_folder_path
 from unique_sdk.cli.state import ShellState
 from unique_sdk.utils.file_io import download_content, upload_file
@@ -40,9 +41,6 @@ _SUPPORTED_UPLOAD_MIME_TYPES = {
 
 # Bounds so one name resolve can never page through the whole knowledge base.
 _MAX_RESOLVE_MATCH_CANDIDATES = 100
-_MAX_RESOLVE_INFOS_PAGES = 10
-_RESOLVE_INFOS_PAGE_SIZE = 100
-_MAX_RESOLVE_INFOS_ENTRIES = _MAX_RESOLVE_INFOS_PAGES * _RESOLVE_INFOS_PAGE_SIZE
 
 
 def _normalize_unique_file_path(cwd: str, path: str) -> str:
@@ -178,19 +176,10 @@ def _resolve_content_id_in_folder(
         ),
         lookup_name=lookup_name,
     )
-    capped = False
     if match is None:
-        hits, capped = _hits_by_search(
-            state=state, lookup_name=lookup_name, scope_id=scope_id
-        )
+        hits = _hits_by_search(state=state, lookup_name=lookup_name, scope_id=scope_id)
         match = _pick_match(hits=hits, lookup_name=lookup_name)
     if match is None:
-        if capped:
-            raise ValueError(
-                f"File not found in the first {_MAX_RESOLVE_INFOS_ENTRIES} "
-                f"entries of this folder: {name_or_id}. Use 'unique-cli "
-                "search' or pass a content id (cont_...)."
-            )
         raise ValueError(f"File not found: {name_or_id}")
 
     resolved_id, display_name = match
@@ -234,8 +223,7 @@ def _hits_by_file_path(
 
 def _hits_by_search(
     *, state: ShellState, lookup_name: str, scope_id: str
-) -> tuple[Sequence[Any], bool]:
-    """Return the hits, and whether the get_infos fallback hit its page cap."""
+) -> Sequence[Any]:
     try:
         hits = unique_sdk.Content.search(
             user_id=state.config.user_id,
@@ -259,7 +247,7 @@ def _hits_by_search(
             lookup_name=lookup_name,
             scope_id=scope_id,
         )
-    return hits, False
+    return hits
 
 
 def _pick_match(*, hits: Sequence[Any], lookup_name: str) -> tuple[str, str] | None:
@@ -290,32 +278,21 @@ def _resolve_content_id_via_infos_fallback(
     state: ShellState,
     lookup_name: str,
     scope_id: str,
-) -> tuple[list[Mapping[str, Any]], bool]:
-    """Folder-scoped get_infos fallback with a hard page cap.
-
-    Returns the match (if any), and whether the cap stopped the scan early.
-    """
-    skip = 0
-    for _ in range(_MAX_RESOLVE_INFOS_PAGES):
-        result = unique_sdk.Content.get_infos(
-            user_id=state.config.user_id,
-            company_id=state.config.company_id,
-            parentId=scope_id,
-            skip=skip,
-            take=_RESOLVE_INFOS_PAGE_SIZE,
-        )
-        content_infos = result.get("contentInfos", [])
-        if not content_infos:
-            return [], False
-        for info in content_infos:
-            title = info.get("title") or ""
-            key = info.get("key") or ""
-            if lookup_name in {title, key}:
-                return [info], False
-        if len(content_infos) < _RESOLVE_INFOS_PAGE_SIZE:
-            return [], False
-        skip += len(content_infos)
-    return [], True
+) -> list[Mapping[str, Any]]:
+    """Folder-scoped get_infos fallback, filtered by name so one page suffices."""
+    name_filter = {
+        "or": [
+            {"path": ["title"], "operator": "equals", "value": lookup_name},
+            {"path": ["key"], "operator": "equals", "value": lookup_name},
+        ]
+    }
+    result = unique_sdk.Content.get_infos(
+        user_id=state.config.user_id,
+        company_id=state.config.company_id,
+        metadataFilter={"and": [direct_children_filter(scope_id), name_filter]},
+        take=_MAX_RESOLVE_MATCH_CANDIDATES,
+    )
+    return list(result.get("contentInfos", []))
 
 
 def _detect_upload_mime_type(path: Path) -> str:

{unique_sdk-2026.44.0.dev12 → unique_sdk-2026.44.0.dev14}/unique_sdk/cli/commands/navigation.py

@@ -2,14 +2,24 @@
 
 from __future__ import annotations
 
+import shlex
+from collections.abc import Callable, Mapping
 from typing import Any
 
 import unique_sdk
 from unique_sdk.cli.formatting import format_ls
-from unique_sdk.cli.metadata_filter import _collect_filter_targets
+from unique_sdk.cli.metadata_filter import (
+    _collect_filter_targets,
+    direct_children_filter,
+)
 from unique_sdk.cli.paths import canonical_folder_path, same_folder_path
 from unique_sdk.cli.state import ShellState
 
+# Server take is capped at 100 and defaults to 50; ls pages to reach --limit rows.
+LS_PAGE_SIZE = 100
+LS_DEFAULT_LIMIT = 50
+LS_MAX_LIMIT = 1000
+
 
 def cmd_pwd(state: ShellState) -> str:
     return state.cwd
@@ -84,8 +94,90 @@ def is_ls_error_output(output: str) -> bool:
     return output.startswith("ls:")
 
 
-def cmd_ls(state: ShellState, target: str | None = None) -> str:
-    """List folders and files at the given (or current) path."""
+def _fetch_window(
+    fetch_page: Callable[[int, int], Mapping[str, Any]],
+    rows_key: str,
+    skip: int,
+    limit: int,
+) -> tuple[list[Any], int]:
+    """Return up to *limit* rows starting at *skip*, and the API total."""
+    rows: list[Any] = []
+    total: int | None = None
+    offset = skip
+    while len(rows) < limit:
+        take = min(LS_PAGE_SIZE, limit - len(rows))
+        result = fetch_page(offset, take)
+        page = result.get(rows_key, [])
+        total = result.get("totalCount", total)
+        rows.extend(page)
+        offset += len(page)
+        if len(page) < take or (total is not None and offset >= total):
+            break
+    return rows, total if total is not None else skip + len(rows)
+
+
+def _window_note(
+    label: str,
+    skip: int,
+    limit: int,
+    shown: dict[str, int],
+    totals: dict[str, int],
+    hidden_files: int = 0,
+) -> str:
+    """Say which rows this call read and how to list the rest; empty when complete.
+
+    ``shown`` counts rows read from the server. ``hidden_files`` of them were
+    dropped by the task scope and are not printed, so the wording says "read".
+    """
+    parts: list[str] = []
+    for kind in ("folders", "files"):
+        total = totals[kind]
+        count = shown[kind]
+        if total == 0 or (skip == 0 and count >= total):
+            continue
+        if count == 0:
+            parts.append(f"no {kind} after {skip} (of {total})")
+        else:
+            parts.append(f"{kind} {skip + 1}-{skip + count} of {total}")
+    if not parts:
+        return ""
+    verb = "read" if hidden_files else "showing"
+    note = f"\n{verb} " + ", ".join(parts)
+    if hidden_files:
+        note += f" ({hidden_files} file(s) hidden by task scope)"
+    if any(skip + shown[kind] < totals[kind] for kind in shown):
+        quoted = shlex.quote(label)
+        limit_arg = "" if limit == LS_DEFAULT_LIMIT else f" --limit {limit}"
+        note += f"\nmore: unique-cli ls {quoted} --skip {skip + limit}{limit_arg}"
+        # --all restarts at row 0, so it only helps when it would show more
+        # than this window already does; at the cap it would repeat rows.
+        if skip == 0 and limit < LS_MAX_LIMIT:
+            note += f" (or: unique-cli ls {quoted} --all)"
+    return note
+
+
+def cmd_ls(
+    state: ShellState,
+    target: str | None = None,
+    *,
+    skip: int = 0,
+    limit: int = LS_DEFAULT_LIMIT,
+    all_items: bool = False,
+) -> str:
+    """List folders and files at the given (or current) path.
+
+    Shows up to *limit* folders and *limit* files starting at *skip*
+    (``all_items`` raises *limit* to ``LS_MAX_LIMIT``). When more exist, the
+    output says which rows are shown and ends with the ``ls`` call for the rest.
+    """
+    if all_items and limit != LS_DEFAULT_LIMIT:
+        return "ls: --all and --limit cannot be combined"
+    if all_items:
+        limit = LS_MAX_LIMIT
+    if skip < 0:
+        return "ls: --skip must be 0 or more"
+    if not 1 <= limit <= LS_MAX_LIMIT:
+        return f"ls: --limit must be between 1 and {LS_MAX_LIMIT}"
     try:
         if target is not None:
             resolved_path, scope_id = state.resolve_path(target)
@@ -105,6 +197,16 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                 f"({state.scope_denial_hint()})."
             )
 
+        # The scoped root lists a fixed set of folders; there is nothing to page.
+        if (
+            scope_id is None
+            and skip
+            and (
+                state.workspace_metadata_filter is not None or state.workspace_scope_ids
+            )
+        ):
+            return "ls: paging is not supported at the scoped root"
+
         # At root with a per-message KB scope (e.g. an Agentic Table column's
         # scope_rules), show only the in-scope folders and explicitly-scoped
         # documents so the agent explores within the boundary rather than the
@@ -188,29 +290,39 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                 return path_error
 
         folder_params: dict[str, Any] = {}
-        content_params: dict[str, Any] = {}
         if scope_id:
             folder_params["parentId"] = scope_id
-            content_params["parentId"] = scope_id
 
-        folder_result = unique_sdk.Folder.get_infos(
-            user_id=state.config.user_id,
-            company_id=state.config.company_id,
-            **folder_params,
+        folders, total_folders = _fetch_window(
+            lambda offset, take: unique_sdk.Folder.get_infos(
+                user_id=state.config.user_id,
+                company_id=state.config.company_id,
+                skip=offset,
+                take=take,
+                **folder_params,
+            ),
+            "folderInfos",
+            skip,
+            limit,
         )
-        folders = folder_result.get("folderInfos", [])
-
-        content_result = unique_sdk.Content.get_infos(
-            user_id=state.config.user_id,
-            company_id=state.config.company_id,
-            **content_params,
-        )
-        files = content_result.get("contentInfos", [])
-
-        total_folders = folder_result.get("totalCount", len(folders))
-        total_files = content_result.get("totalCount", len(files))
+        # Every file lives in a folder, so the root has no files of its own.
+        files: list[Any] = []
+        total_files = 0
+        if scope_id:
+            files, total_files = _fetch_window(
+                lambda offset, take: unique_sdk.Content.get_infos(
+                    user_id=state.config.user_id,
+                    company_id=state.config.company_id,
+                    metadataFilter=direct_children_filter(scope_id),
+                    skip=offset,
+                    take=take,
+                ),
+                "contentInfos",
+                skip,
+                limit,
+            )
 
-        if scope_id and not folders and not files:
+        if scope_id and not folders and not files and skip == 0:
             label = target if target is not None else resolved_path
             counts_error = _counts_without_rows_error(
                 label,
@@ -225,25 +337,36 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
         # allowlist): read/cite would deny them, so ls must hide them too.
         # Folder-only filters keep every file (each passes the folderIdPath
         # leaf); the verdict is cached per content id. See UN-21780.
+        # The paging note counts rows read from the server, before the scope filter.
+        scanned_files = len(files)
         if state.workspace_metadata_filter is not None:
             files = [
                 f for f in files if state.is_content_within_workspace(f.get("id", ""))
             ]
+        note = _window_note(
+            target if target is not None else resolved_path,
+            skip,
+            limit,
+            {"folders": len(folders), "files": scanned_files},
+            {"folders": total_folders, "files": total_files},
+            hidden_files=scanned_files - len(files),
+        )
+
+        output = format_ls(folders, files)
+        if state.workspace_metadata_filter is not None:
             # ``files`` is only the current API page, so the in-scope count is
             # per-page, not the folder total. Report it as the shown-in-scope
             # count and keep the API ``totalCount`` as the folder's real size,
             # rather than overwriting total_files with the page length (which
             # would silently undercount paginated folders). See UN-21780.
-            output = format_ls(folders, files)
             summary = (
                 f"\n{total_folders} folder(s), {len(files)} file(s) in task scope "
                 f"(of {total_files} in folder)"
             )
-            return output + summary
+            return output + summary + note
 
-        output = format_ls(folders, files)
         summary = f"\n{total_folders} folder(s), {total_files} file(s)"
-        return output + summary
+        return output + summary + note
 
     except (ValueError, unique_sdk.UniqueError) as e:
         return f"ls: {e}"

{unique_sdk-2026.44.0.dev12 → unique_sdk-2026.44.0.dev14}/unique_sdk/cli/metadata_filter.py

@@ -38,6 +38,20 @@ ScopePathResolver = Callable[[str], "str | None"]
 ContentOwnerPathResolver = Callable[[str], "str | None"]
 
 
+def direct_children_filter(scope_id: str) -> dict[str, Any]:
+    """UniqueQL for files directly in ``scope_id``, not in its subfolders."""
+    return {
+        "and": [
+            {"path": ["folderIdPath"], "operator": "contains", "value": scope_id},
+            {
+                "path": ["folderIdPath"],
+                "operator": "notContains",
+                "value": f"{scope_id}/",
+            },
+        ]
+    }
+
+
 def _extract_target_scope_id(value: Any) -> str | None:
     """Deepest folder scope id referenced by a ``folderIdPath`` filter value.
 

{unique_sdk-2026.44.0.dev12 → unique_sdk-2026.44.0.dev14}/unique_sdk/cli/shell.py

@@ -27,7 +27,12 @@ from unique_sdk.cli.commands.files import (
 )
 from unique_sdk.cli.commands.folders import cmd_mkdir, cmd_mvdir, cmd_rmdir
 from unique_sdk.cli.commands.mcp import cmd_mcp
-from unique_sdk.cli.commands.navigation import cmd_cd, cmd_ls, cmd_pwd
+from unique_sdk.cli.commands.navigation import (
+    LS_DEFAULT_LIMIT,
+    cmd_cd,
+    cmd_ls,
+    cmd_pwd,
+)
 from unique_sdk.cli.commands.scheduled_tasks import (
     cmd_schedule_create,
     cmd_schedule_delete,
@@ -217,10 +222,12 @@ class UniqueShell(cmd.Cmd):
     def do_ls(self, arg: str) -> None:
         """List folders and files in a directory.
 
-        Usage: ls [target]
+        Usage: ls [target] [--limit N] [--skip N] [--all]
 
         Without arguments, lists the current directory. With an argument,
         lists the specified folder (by name, path, or scope ID).
+        Shows 50 folders and 50 files by default; when a folder holds more,
+        the output says so and prints the command for the rest.
 
         Output columns: TYPE  NAME  ID  SIZE  UPDATED
 
@@ -233,8 +240,51 @@ class UniqueShell(cmd.Cmd):
           /> ls /Reports/Q1
           /> ls scope_abc123
         """
-        target = arg.strip() or None
-        self._print(cmd_ls(self.state, target))
+        try:
+            parts = shlex.split(arg)
+        except ValueError as e:
+            self._print(f"ls: {e}")
+            return
+        target: str | None = None
+        skip = 0
+        limit = LS_DEFAULT_LIMIT
+        all_items = False
+        # Accept --limit=20 / --skip=50 like the one-shot CLI does.
+        expanded: list[str] = []
+        for part in parts:
+            name, sep, value = part.partition("=")
+            if sep and name in ("--limit", "--skip"):
+                expanded.extend([name, value])
+            else:
+                expanded.append(part)
+        it = iter(expanded)
+        for part in it:
+            if part in ("--all", "-a"):
+                all_items = True
+            elif part in ("--limit", "-l", "--skip"):
+                value = next(it, None)
+                try:
+                    number = int(value) if value is not None else None
+                except ValueError:
+                    number = None
+                if number is None:
+                    self._print(f"ls: {part} needs a whole number")
+                    return
+                if part == "--skip":
+                    skip = number
+                else:
+                    limit = number
+            elif part.startswith("-") and len(part) > 1:
+                self._print(f"ls: unknown option {part}")
+                return
+            elif target is None:
+                target = part
+            else:
+                self._print("ls: expected at most one target")
+                return
+        self._print(
+            cmd_ls(self.state, target, skip=skip, limit=limit, all_items=all_items)
+        )
 
     # -- Folder operations --
 

{unique_sdk-2026.44.0.dev12 → unique_sdk-2026.44.0.dev14}/unique_sdk/cli/skills/unique-cli-file-management/SKILL.md

@@ -42,6 +42,11 @@ unique-cli ls /Reports/Q1
 # List by scope ID
 unique-cli ls scope_abc123
 
+# Large folder: ls shows 50 folders and 50 files by default. When it prints
+# "showing files 1-50 of N", run the "more:" command it gives you
+unique-cli ls /Reports/Q1 --skip 50      # next page
+unique-cli ls /Reports/Q1 --all          # up to 1000 folders and 1000 files
+
 # Create a folder
 unique-cli mkdir Q2
 

{unique_sdk-2026.44.0.dev12 → unique_sdk-2026.44.0.dev14}/unique_sdk/cli/skills/unique-cli-search/SKILL.md

@@ -12,7 +12,8 @@ description: >-
   (.xlsx/.xls), CSV (.csv), and image files are NOT full-text indexed,
   so they will not appear in search results. To locate these file types,
   use the unique-cli-file-management skill instead (browse folders with
-  `unique-cli ls` to find them by name).
+  `unique-cli ls` to find them by name; `ls` shows 50 files at a time, so
+  follow its "more:" line or use `--all` for larger folders).
 ---
 
 # Unique CLI -- Knowledge Base Search & Document Read
@@ -32,7 +33,7 @@ Use `read` after a `ls` or `search` surfaces a content ID and you need to go dee
 
 Search the Unique knowledge base using combined vector + full-text search via the `unique-cli search` command. Every invocation wraps each result in a `<sourceN>...</sourceN>` block and records a per-turn citation manifest at `.unique/kb-search-refs.jsonl`, so any fact you cite as `[sourceN]` is rendered with a footnote and a clickable reference chip in the chat UI.
 
-> **Limitation:** Excel (`.xlsx`/`.xls`), CSV (`.csv`), and image files are **not** full-text indexed. They will not appear in search results. To find these files, use the `unique-cli-file-management` skill and browse folders with `unique-cli ls` to locate them by name.
+> **Limitation:** Excel (`.xlsx`/`.xls`), CSV (`.csv`), and image files are **not** full-text indexed. They will not appear in search results. To find these files, use the `unique-cli-file-management` skill and browse folders with `unique-cli ls` to locate them by name (`ls` shows 50 files at a time; follow its "more:" line or use `--all` for larger folders).
 
 
 ## Basic Search