unique-sdk 2026.28.0.dev6__tar.gz → 2026.28.0.dev8__tar.gz

{unique_sdk-2026.28.0.dev6 → unique_sdk-2026.28.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.28.0.dev6
+Version: 2026.28.0.dev8
 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.28.0.dev6 → unique_sdk-2026.28.0.dev8}/pyproject.toml

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

{unique_sdk-2026.28.0.dev6 → unique_sdk-2026.28.0.dev8}/unique_sdk/cli/cli.py

@@ -2,12 +2,16 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from typing import Any
 
 import click
 
 from unique_sdk.cli import __version__
 from unique_sdk.cli.commands.cite_file import cmd_cite_file
+from unique_sdk.cli.commands.cite_file import (
+    is_error_output as _is_cite_error_output,
+)
 from unique_sdk.cli.commands.dynamic_frontend import (
     cmd_dynamic_frontend_delete,
     cmd_dynamic_frontend_deploy,
@@ -30,6 +34,9 @@ from unique_sdk.cli.commands.files import (
     cmd_upload,
     cmd_versions,
 )
+from unique_sdk.cli.commands.files import (
+    is_permission_denied_output as _is_permission_denied_output,
+)
 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
@@ -132,6 +139,25 @@ class LazyState:
         return ctx.obj
 
 
+def emit(
+    output: str,
+    *,
+    is_error: Callable[[str], bool] = _is_permission_denied_output,
+) -> None:
+    """Print a command's *output* and exit non-zero when it is an error.
+
+    Errors (e.g. a scope denial) are written to stderr and raise
+    ``SystemExit(1)`` so agent ``&&`` chains stop cleanly; successful output
+    goes to stdout. The default predicate matches the ``<cmd>: permission
+    denied`` shape shared by the scope-gated commands; pass ``is_error`` for
+    commands with their own error-detection helper (cite/read/search/...).
+    """
+    if is_error(output):
+        click.echo(output, err=True)
+        raise SystemExit(1)
+    click.echo(output)
+
+
 @click.group(invoke_without_command=True, help=MAIN_HELP)
 @click.version_option(version=__version__, prog_name="unique-cli")
 @click.pass_context
@@ -203,7 +229,8 @@ def ls(ctx: click.Context, target: str | None) -> None:
       unique-cli ls /Reports     List a specific path
       unique-cli ls scope_abc    List by scope ID
     """
-    click.echo(cmd_ls(LazyState.get(ctx), target))
+    output = cmd_ls(LazyState.get(ctx), target)
+    emit(output)
 
 
 @main.command()
@@ -221,7 +248,8 @@ def mkdir(ctx: click.Context, name: str) -> None:
       unique-cli mkdir Q2
       unique-cli mkdir "2025/Q1"
     """
-    click.echo(cmd_mkdir(LazyState.get(ctx), name))
+    output = cmd_mkdir(LazyState.get(ctx), name)
+    emit(output)
 
 
 @main.command()
@@ -246,7 +274,8 @@ def rmdir(ctx: click.Context, target: str, recursive: bool) -> None:
       unique-cli rmdir /Reports/Q1 --recursive
       unique-cli rmdir scope_abc123 -r
     """
-    click.echo(cmd_rmdir(LazyState.get(ctx), target, recursive=recursive))
+    output = cmd_rmdir(LazyState.get(ctx), target, recursive=recursive)
+    emit(output)
 
 
 @main.command()
@@ -265,7 +294,8 @@ def mvdir(ctx: click.Context, old_name: str, new_name: str) -> None:
       unique-cli mvdir Q1 "Q1-2025"
       unique-cli mvdir scope_abc123 "New Name"
     """
-    click.echo(cmd_mvdir(LazyState.get(ctx), old_name, new_name))
+    output = cmd_mvdir(LazyState.get(ctx), old_name, new_name)
+    emit(output)
 
 
 @main.command()
@@ -298,7 +328,8 @@ def upload(ctx: click.Context, local_path: str, destination: str | None) -> None
       unique-cli upload ./report.pdf Q1/
       unique-cli upload ./report.pdf /Archive/2025/
     """
-    click.echo(cmd_upload(LazyState.get(ctx), local_path, destination))
+    output = cmd_upload(LazyState.get(ctx), local_path, destination)
+    emit(output)
 
 
 @main.command()
@@ -324,7 +355,8 @@ def versions(
       unique-cli versions /Reports/Q1/report.pdf
       unique-cli versions cont_abc123 --take 10
     """
-    click.echo(cmd_versions(LazyState.get(ctx), name_or_id, skip=skip, take=take))
+    output = cmd_versions(LazyState.get(ctx), name_or_id, skip=skip, take=take)
+    emit(output)
 
 
 @main.command(name="restore-version")
@@ -340,7 +372,8 @@ def restore_version(ctx: click.Context, content_version_id: str) -> None:
     Examples:
       unique-cli restore-version cver_abc123
     """
-    click.echo(cmd_restore_version(LazyState.get(ctx), content_version_id))
+    output = cmd_restore_version(LazyState.get(ctx), content_version_id)
+    emit(output)
 
 
 @main.command()
@@ -365,7 +398,8 @@ def download(ctx: click.Context, name_or_id: str, local_dest: str | None) -> Non
       unique-cli download annual.pdf ./downloads/
       unique-cli download cont_abc123 ~/Desktop/
     """
-    click.echo(cmd_download(LazyState.get(ctx), name_or_id, local_dest))
+    output = cmd_download(LazyState.get(ctx), name_or_id, local_dest)
+    emit(output)
 
 
 @main.command(name="cite")
@@ -414,7 +448,8 @@ def cite(
       unique-cli cite cont_abc123 --pages 1-4 --read-method indexed
       unique-cli cite notes.docx --read-method text
     """
-    click.echo(cmd_cite_file(LazyState.get(ctx), name_or_id, pages, read_method))
+    output = cmd_cite_file(LazyState.get(ctx), name_or_id, pages, read_method)
+    emit(output, is_error=_is_cite_error_output)
 
 
 @main.command(name="read")
@@ -492,10 +527,7 @@ def read_cmd(
         to_page=to_page,
         max_chars=max_chars,
     )
-    if _is_read_error_output(output):
-        click.echo(output, err=True)
-        raise SystemExit(1)
-    click.echo(output)
+    emit(output, is_error=_is_read_error_output)
 
 
 @main.group(name="dynamic-frontend")
@@ -609,7 +641,8 @@ def rm(ctx: click.Context, name_or_id: str) -> None:
       unique-cli rm /Reports/Q1/report.pdf
       unique-cli rm cont_abc123
     """
-    click.echo(cmd_rm(LazyState.get(ctx), name_or_id))
+    output = cmd_rm(LazyState.get(ctx), name_or_id)
+    emit(output)
 
 
 @main.command()
@@ -629,7 +662,8 @@ def mv(ctx: click.Context, old_name: str, new_name: str) -> None:
       unique-cli mv /Reports/Q1/annual.pdf annual-2025.pdf
       unique-cli mv cont_abc123 "New Title.pdf"
     """
-    click.echo(cmd_mv_file(LazyState.get(ctx), old_name, new_name))
+    output = cmd_mv_file(LazyState.get(ctx), old_name, new_name)
+    emit(output)
 
 
 @main.command()
@@ -638,7 +672,11 @@ def mv(ctx: click.Context, old_name: str, new_name: str) -> None:
     "--folder",
     "-f",
     default=None,
-    help="Restrict search to a folder (path, name, or scope ID). Defaults to current directory.",
+    help=(
+        "Restrict search to a folder (path, name, or scope ID). Without an "
+        "active task scope, defaults to the current directory; with one, the "
+        "task scope is the boundary and --folder ANDs an extra constraint."
+    ),
 )
 @click.option(
     "--metadata",
@@ -668,9 +706,12 @@ def search(
     both semantic similarity and keyword matching.
 
     \b
-    By default, searches within the current directory scope with up
-    to 200 results. Use --folder to target a different folder, and
-    --metadata to filter by custom metadata fields.
+    Without an active task scope, searches within the current directory
+    scope with up to 200 results; use --folder to target a different
+    folder. When the task defines a per-message scope, that scope is the
+    search boundary regardless of the current directory, and --folder
+    ANDs an additional constraint. Use --metadata to filter by custom
+    metadata fields.
 
     \b
     Examples:

{unique_sdk-2026.28.0.dev6 → unique_sdk-2026.28.0.dev8}/unique_sdk/cli/commands/cite_file.py

@@ -131,12 +131,27 @@ def _resolve_content_id_with_manifest(
     """Resolve a filename/content_id checking the chat-files manifest first.
 
     Resolution order:
-    1. If name_or_id starts with "cont_", return it directly.
+    1. If name_or_id starts with "cont_", resolve its title via the API so the
+       citation renders with the document filename, not the opaque id.
     2. Check .unique/chat-files.json for a matching filename (exact or basename).
     3. Fall back to KB resolution via _resolve_content_id.
     """
     if name_or_id.startswith("cont_"):
-        return name_or_id, name_or_id
+        # Gate the id *before* resolving its title, exactly like read's cont_
+        # fast-path (_resolve_content_id): resolve_content_title hits
+        # Content.get_info, so checking scope afterwards would probe the KB
+        # ahead of denial (a cross-scope existence/title oracle) and — without
+        # a per-message filter — skip the static scopeIds boundary that read
+        # enforces. is_content_within_workspace covers both the per-message
+        # filter and the static scope, and keeps the read-only chat-attachment
+        # exemption. See UN-21780.
+        if not state.is_content_within_workspace(name_or_id):
+            raise ValueError(
+                f"permission denied: {name_or_id} is outside your task scope "
+                f"({state.scope_denial_hint()}). Only cite documents within that "
+                "scope or files attached to this chat."
+            )
+        return name_or_id, state.resolve_content_title(name_or_id)
 
     manifest_path = Path.cwd() / _CHAT_FILES_MANIFEST
     if manifest_path.is_file():
@@ -181,6 +196,20 @@ def cmd_cite_file(
     except Exception as exc:
         return f"{CITE_ERROR_PREFIX} {exc}"
 
+    # When a per-message KB scope filter is active (e.g. an Agentic Table
+    # column's scope_rules), don't let the agent cite documents outside it.
+    # Chat-attached files are exempt — is_content_within_workspace allows them.
+    # Static-scope (no per-message filter) cite behaviour is left unchanged.
+    if (
+        state.workspace_metadata_filter is not None
+        and not state.is_content_within_workspace(content_id)
+    ):
+        return (
+            f"{CITE_ERROR_PREFIX} permission denied: {content_id} is outside your "
+            f"task scope ({state.scope_denial_hint()}). Only cite documents within "
+            "that scope or files attached to this chat."
+        )
+
     if pages and pages.strip() and _is_non_paginated(filename):
         suffix = Path(filename).suffix.lower()
         return (
@@ -253,3 +282,13 @@ def cmd_cite_file(
         return f"{CITE_ERROR_PREFIX} {exc}"
 
     return "\n".join(output_lines)
+
+
+def is_error_output(output: str) -> bool:
+    """Return ``True`` when *output* is an error message from ``cmd_cite_file``.
+
+    Lets the one-shot dispatcher exit non-zero (so shell ``&&`` chains stop) on
+    any cite failure — invalid pages, missing file, or an out-of-scope denial.
+    Mirrors ``read.is_error_output``.
+    """
+    return output.startswith(CITE_ERROR_PREFIX)

{unique_sdk-2026.28.0.dev6 → unique_sdk-2026.28.0.dev8}/unique_sdk/cli/commands/files.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import mimetypes
+import re
 import shutil
 from collections.abc import Mapping, Sequence
 from pathlib import Path
@@ -13,6 +14,19 @@ from unique_sdk.cli.formatting import format_content_info
 from unique_sdk.cli.state import ShellState
 from unique_sdk.utils.file_io import download_content, upload_file
 
+# A denial result has the shape ``<command>: permission denied[…]`` (the
+# command token is lowercase, e.g. ``upload``/``ls``/``restore-version``) and
+# is always the *first thing* in the result string — each command returns the
+# denial verbatim (e.g. ``"upload: permission denied: …"``, ``"read:
+# permission denied: …"``). Anchor at the start of the string only: with
+# re.MULTILINE, ``^`` would match the start of any line, so a multi-line
+# *success* output containing a line shaped like ``token: permission denied``
+# mid-result (e.g. quoted document text) would trigger a false non-zero exit.
+# Successful results also start with a capitalised past-tense verb ("Uploaded:",
+# "Downloaded:", "Renamed", "Restored:"), so the lowercase-prefix anchor never
+# misfires on them. See UN-21780.
+_PERMISSION_DENIED_RE = re.compile(r"^[a-z][a-z0-9-]*: permission denied")
+
 _SUPPORTED_UPLOAD_MIME_TYPES = {
     ".pdf": "application/pdf",
     ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
@@ -42,15 +56,25 @@ def _normalize_unique_file_path(cwd: str, path: str) -> str:
     return "/" + "/".join(parts)
 
 
-def _resolve_content_id(state: ShellState, name_or_id: str) -> tuple[str, str]:
+def _resolve_content_id(
+    state: ShellState, name_or_id: str, *, allow_chat_files: bool = True
+) -> tuple[str, str]:
     """Resolve a file name or content ID to (content_id, display_name).
 
     Accepts a content ID (cont_...), a file name in the current folder,
-    or an absolute/relative Unique file path.
+    or an absolute/relative Unique file path. Pass ``allow_chat_files=False``
+    from destructive ops so the chat-attachment exemption (read-only intent)
+    can't be used to delete/rename out-of-scope content. See UN-21780.
     """
     if name_or_id.startswith("cont_"):
-        if not state.is_content_within_workspace(name_or_id):
-            raise ValueError("permission denied (outside workspace scope)")
+        if not state.is_content_within_workspace(
+            name_or_id, allow_chat_files=allow_chat_files
+        ):
+            raise ValueError(
+                f"permission denied: {name_or_id} is outside your task scope "
+                f"({state.scope_denial_hint()}). Use 'unique-cli search' or "
+                "'ls' within that scope instead."
+            )
         return name_or_id, name_or_id
 
     lookup_name = name_or_id
@@ -62,7 +86,32 @@ def _resolve_content_id(state: ShellState, name_or_id: str) -> tuple[str, str]:
             raise ValueError(f"File path must include a file name: {name_or_id}")
         if not folder_path:
             folder_path = "/"
-        if not state.is_folder_target_within_workspace(folder_path):
+        # An active per-message filter replaces the static scopeIds for content
+        # access. Gate the *folder* against the navigable filter scope before
+        # Folder.get_info + the name scan: deferring solely to the per-id gate
+        # lets a path into an out-of-scope folder resolve the file and surface a
+        # task-scope "permission denied" instead of "File not found", leaking
+        # cross-boundary existence — the same oracle closed for bare filenames
+        # at root. The path check is structural (no API call), so it denies
+        # uniformly whether or not the file exists. See UN-21780.
+        if state.workspace_metadata_filter is not None:
+            # Only gate the folder when the filter actually constrains folders.
+            # A pure contentId scope has no navigable folders, so the document
+            # may live anywhere and the per-id gate below is authoritative —
+            # gating on folder here would wrongly deny it. When the filter does
+            # name folders, a path outside them is denied structurally (no API
+            # call), so an out-of-scope file can't leak existence via the per-id
+            # "permission denied" vs "File not found" distinction.
+            if (
+                state.navigable_folder_ids()
+                and not state.folder_path_allowed_by_metadata_filter(folder_path)
+            ):
+                raise ValueError(
+                    f"permission denied: {name_or_id} is outside your task scope "
+                    f"({state.scope_denial_hint()}). Use 'unique-cli search' or "
+                    "'ls' within that scope instead."
+                )
+        elif not state.is_folder_target_within_workspace(folder_path):
             raise ValueError("permission denied (outside workspace scope)")
 
         info = unique_sdk.Folder.get_info(
@@ -73,8 +122,26 @@ def _resolve_content_id(state: ShellState, name_or_id: str) -> tuple[str, str]:
         scope_id = info.get("id")
         if not scope_id:
             raise ValueError(f"folder not found: {folder_path}")
-    elif not state.is_within_workspace():
-        raise ValueError("permission denied (outside workspace scope)")
+    elif scope_id is None:
+        # A bare file name with no folder context resolves via an *unparented*
+        # Content.get_infos scan across the whole knowledge base.
+        if state.workspace_metadata_filter is not None:
+            # With a per-message filter active, a whole-KB filename scan would
+            # discover documents outside the task scope before the per-id gate
+            # runs — and the deny-vs-not-found distinction is an existence/title
+            # oracle across the task boundary. That is broader than the
+            # ls/read-at-root gating intent, so require a bounded context
+            # instead. The cont_ fast-path, an explicit in-scope path, or a
+            # ``cd`` into an in-scope folder all still work. See UN-21780.
+            raise ValueError(
+                f"permission denied: {name_or_id} can't be resolved by name at "
+                f"the knowledge-base root while a task scope is active "
+                f"({state.scope_denial_hint()}). Use 'unique-cli search', cite "
+                "by content id, or 'cd' into an in-scope folder."
+            )
+        if not state.is_within_workspace():
+            # No per-message filter: defer to the static scopeIds boundary.
+            raise ValueError("permission denied (outside workspace scope)")
 
     params: dict[str, Any] = {}
     if scope_id:
@@ -98,7 +165,22 @@ def _resolve_content_id(state: ShellState, name_or_id: str) -> tuple[str, str]:
             title = info.get("title") or ""
             key = info.get("key") or ""
             if lookup_name in {title, key}:
-                return info["id"], title or key
+                resolved_id = info["id"]
+                # Gate the *resolved* id too: resolving by file name or path
+                # must not bypass the per-message metadata-filter scope that
+                # the cont_ fast-path above enforces, and must honour the same
+                # read-only chat-file exemption (so rm/mv by name can't reach
+                # an out-of-scope attachment either). See UN-21780.
+                if not state.is_content_within_workspace(
+                    resolved_id, allow_chat_files=allow_chat_files
+                ):
+                    raise ValueError(
+                        f"permission denied: {name_or_id} is outside your "
+                        f"task scope ({state.scope_denial_hint()}). Use "
+                        "'unique-cli search' or 'ls' within that scope "
+                        "instead."
+                    )
+                return resolved_id, title or key
 
         skip += len(content_infos)
 
@@ -221,7 +303,14 @@ def cmd_upload(
     upload file.pdf /abs/path/   -> into absolute path folder
     """
     dest = destination or "."
-    if not state.is_folder_target_within_workspace(dest):
+    # A per-message metaDataFilter *replaces* the static scopeIds (read/search/
+    # ls honour the filter, not scopeIds), so the static-scope check must not
+    # over-deny an in-filter destination. When a filter is active the resolved
+    # scope id is gated against it below instead. See UN-21780.
+    if (
+        state.workspace_metadata_filter is None
+        and not state.is_folder_target_within_workspace(dest)
+    ):
         return "upload: permission denied (outside workspace scope)"
     try:
         path = Path(local_path).expanduser().resolve()
@@ -234,6 +323,21 @@ def cmd_upload(
             destination,
         )
 
+        # is_folder_target_within_workspace only enforces the static
+        # scopeIds; when the runner supplies a per-message metaDataFilter
+        # without scopeIds it treats every folder as writable. Gate the
+        # resolved destination against the per-message filter too, so uploads
+        # can't escape a task scope that read/download/ls/search honor.
+        # See UN-21780.
+        if (
+            state.workspace_metadata_filter is not None
+            and not state.folder_allowed_by_metadata_filter(scope_id)
+        ):
+            return (
+                "upload: permission denied: destination is outside your "
+                f"task scope ({state.scope_denial_hint()})."
+            )
+
         mime_type = _detect_upload_mime_type(path)
 
         result = upload_file(
@@ -286,6 +390,19 @@ def cmd_versions(
 
 def cmd_restore_version(state: ShellState, content_version_id: str) -> str:
     """Restore a file from an archived content version ID."""
+    # A per-message metaDataFilter is a hard task boundary, but the restore
+    # API only resolves a contentVersionId to its content *after* mutating,
+    # so an out-of-scope version can't be screened beforehand. Deny while a
+    # filter is active rather than allow an unverifiable mutation; reads stay
+    # gated regardless. The filter replaces the static scope for the turn, so
+    # check it *before* the static is_within_workspace() fallback — otherwise
+    # an out-of-static-scope cwd would surface the static denial (no task-scope
+    # hint) even though the filter is authoritative. See UN-21780.
+    if state.workspace_metadata_filter is not None:
+        return (
+            "restore-version: permission denied: cannot verify the target is "
+            f"within your task scope ({state.scope_denial_hint()})."
+        )
     if not state.is_within_workspace():
         return "restore-version: permission denied (outside workspace scope)"
     try:
@@ -338,13 +455,13 @@ def cmd_download(
 
 def cmd_rm(state: ShellState, name_or_id: str) -> str:
     """Delete a file by name or content ID."""
-    if name_or_id.startswith("cont_"):
-        if not state.is_content_within_workspace(name_or_id):
-            return "rm: permission denied (outside workspace scope)"
-    elif not state.is_within_workspace():
-        return "rm: permission denied (outside workspace scope)"
     try:
-        content_id, display_name = _resolve_content_id(state, name_or_id)
+        # Destructive: allow_chat_files=False so the chat-attachment read
+        # exemption can't be used to delete an out-of-scope file. Resolution
+        # also surfaces the task-scope hint on denial. See UN-21780.
+        content_id, display_name = _resolve_content_id(
+            state, name_or_id, allow_chat_files=False
+        )
         unique_sdk.Content.delete(
             user_id=state.config.user_id,
             company_id=state.config.company_id,
@@ -357,13 +474,13 @@ def cmd_rm(state: ShellState, name_or_id: str) -> str:
 
 def cmd_mv_file(state: ShellState, old_name: str, new_name: str) -> str:
     """Rename a file."""
-    if old_name.startswith("cont_"):
-        if not state.is_content_within_workspace(old_name):
-            return "mv: permission denied (outside workspace scope)"
-    elif not state.is_within_workspace():
-        return "mv: permission denied (outside workspace scope)"
     try:
-        content_id, display_name = _resolve_content_id(state, old_name)
+        # Destructive: allow_chat_files=False so the chat-attachment read
+        # exemption can't be used to rename an out-of-scope file. Resolution
+        # also surfaces the task-scope hint on denial. See UN-21780.
+        content_id, display_name = _resolve_content_id(
+            state, old_name, allow_chat_files=False
+        )
         result = unique_sdk.Content.update(
             user_id=state.config.user_id,
             company_id=state.config.company_id,
@@ -373,3 +490,19 @@ def cmd_mv_file(state: ShellState, old_name: str, new_name: str) -> str:
         return f"Renamed: {display_name} -> {result.get('title', new_name)}\n{format_content_info(result)}"
     except (ValueError, unique_sdk.APIError) as e:
         return f"mv: {e}"
+
+
+def is_permission_denied_output(output: str) -> bool:
+    """Return ``True`` when a file-op result is a permission/scope denial.
+
+    Lets the one-shot dispatcher exit non-zero so shell ``&&`` chains stop on
+    an out-of-scope content access instead of continuing as if it succeeded.
+
+    Matches the denial only when it is the *form of the result* — a
+    ``<command>: permission denied`` line — rather than anywhere the substring
+    appears. Denials are emitted as ``"<cmd>: permission denied[ : …]"`` (e.g.
+    ``"upload: permission denied: …"``); anchoring on that shape avoids a
+    false non-zero exit when a successful result happens to contain the phrase
+    (e.g. a filename or document text). See UN-21780.
+    """
+    return bool(_PERMISSION_DENIED_RE.search(output))