mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/attachments/extract.py

@@ -0,0 +1,217 @@
+"""What Mobster derives from an attached file once, when it arrives, so a task never waits on it."""
+
+import csv
+import io
+import json
+import logging
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from . import sniff
+
+log = logging.getLogger("mobster.attachments")
+
+THUMB_PX = 480
+MODEL_PX = 1024
+MAX_PIXELS = 60_000_000
+CSV_ROWS = 200
+OCR_EMPTY_PAGES = 20
+HELPER_TIMEOUT = 90
+TEXT_LIMIT = 8_000_000          # characters of text.txt kept (a 25 MB text file is read whole up to here)
+PAGE = "\f"
+
+
+class TooLarge(ValueError):
+    code = "too_large"
+
+
+class Locked(ValueError):
+    code = "locked_pdf"
+
+
+def _helper_runner(argv, timeout):
+    """Run the doc-text helper; its one JSON line."""
+    done = subprocess.run(argv, capture_output=True, text=True, timeout=timeout, stdin=subprocess.DEVNULL)
+    lines = [line for line in (done.stdout or "").splitlines() if line.startswith("{")]
+    if done.returncode != 0 or not lines:
+        raise RuntimeError(f"doc-text exited {done.returncode}")
+    return lines[-1]
+
+
+# Tests replace these: ``helper`` -> the helper's path (or None), ``run_helper(argv, timeout)`` -> its JSON line.
+def helper_path():
+    from .. import native_helpers
+    found = native_helpers.find("doc-text")
+    if found is not None:
+        return found
+    try:
+        return native_helpers.build("doc_text")
+    except (LookupError, FileNotFoundError, OSError, subprocess.SubprocessError) as error:
+        log.info("doc-text helper unavailable: %s", type(error).__name__)
+        return None
+
+
+run_helper = _helper_runner
+
+
+def _call_helper(*args):
+    path = helper_path()
+    if path is None:
+        return None
+    try:
+        answer = json.loads(run_helper([str(path), *map(str, args)], HELPER_TIMEOUT))
+    except (OSError, ValueError, RuntimeError, subprocess.SubprocessError) as error:
+        log.warning("doc-text failed: %s", type(error).__name__)
+        return None
+    return answer if isinstance(answer, dict) else None
+
+
+def derive(folder, original, file_type):
+    """Write the derived files for ``original`` (in ``folder``) and return what they say about it: {"pages"?, "rows"?,
+    "width"?, "height"?, "textChars", "textAvailable", "thumb", "model", "ocr"}."""
+    folder = Path(folder)
+    if file_type.kind == "image":
+        return _image(folder, original, file_type)
+    if file_type.kind == "pdf":
+        return _pdf(folder, original)
+    text = sniff.decode_text(Path(original).read_bytes()) or ""
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    if file_type.kind == "csv":
+        return _csv(folder, text, file_type)
+    _write_text(folder, text)
+    return {"textChars": min(len(text), TEXT_LIMIT), "textAvailable": True, "thumb": False, "model": False}
+
+
+def _write_text(folder, text):
+    data = text[:TEXT_LIMIT]
+    fd = os.open(folder / "text.txt", os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        handle.write(data)
+
+
+def _csv(folder, text, file_type):
+    delimiter = "\t" if file_type.ext == "tsv" else ","
+    if file_type.ext == "csv":
+        try:
+            delimiter = csv.Sniffer().sniff(text[:20_000], delimiters=",;\t|").delimiter
+        except csv.Error:
+            delimiter = ","
+    head, count = [], 0
+    for row in csv.reader(io.StringIO(text), delimiter=delimiter):
+        if any(cell.strip() for cell in row):
+            count += 1
+            if len(head) <= CSV_ROWS:
+                head.append(row)
+    out = io.StringIO()
+    writer = csv.writer(out, delimiter=delimiter, lineterminator="\n")
+    writer.writerows(head)
+    excerpt = out.getvalue()
+    if count > len(head):
+        excerpt += f"… {count - len(head):,} more rows\n"
+    _write_text(folder, excerpt)
+    return {"rows": max(0, count - 1), "columns": len(head[0]) if head else 0,
+            "textChars": min(len(excerpt), TEXT_LIMIT), "textAvailable": True, "thumb": False, "model": False}
+
+
+def _pdf(folder, original):
+    answer = _call_helper("pdf", original, folder / "text.txt", "--thumb", folder / "thumb.jpg", "--size", THUMB_PX,
+                          "--ocr-empty", OCR_EMPTY_PAGES)
+    if answer is None:
+        return {"textAvailable": False, "textChars": 0, "thumb": False, "model": False}
+    if not answer.get("ok"):
+        if answer.get("error") == "locked":
+            raise Locked("This PDF is locked with a password. Open it, save a copy without the password, then "
+                         "attach that.")
+        raise sniff.Unsupported("This PDF couldn't be opened. It may be damaged.")
+    text = (folder / "text.txt").read_text(errors="replace") if (folder / "text.txt").is_file() else ""
+    if len(text) > TEXT_LIMIT:
+        _write_text(folder, text)
+    return {"pages": int(answer.get("pages") or 0), "textChars": min(len(text), TEXT_LIMIT),
+            "textAvailable": bool(text.replace(PAGE, "").strip()), "thumb": (folder / "thumb.jpg").is_file(),
+            "model": False, "ocrPages": int(answer.get("ocrPages") or 0)}
+
+
+def _image(folder, original, file_type):
+    info = {"thumb": False, "model": False, "textAvailable": False, "textChars": 0}
+    if file_type.mime == "image/heic":
+        info.update(_sips(original, folder))
+    else:
+        info.update(_pillow(original, folder))
+    answer = _call_helper("ocr", original, folder / "text.txt")
+    if answer is not None and answer.get("ok") and (folder / "text.txt").is_file():
+        text = (folder / "text.txt").read_text(errors="replace")
+        info.update(textChars=len(text), textAvailable=bool(text.strip()), ocr=True)
+    return info
+
+
+def _pillow(original, folder):
+    from PIL import Image, ImageOps
+    try:
+        with Image.open(original) as image:
+            width, height = image.size
+            if width * height > MAX_PIXELS:
+                raise TooLarge(f"This image is {width:,} × {height:,} pixels. Mobster reads images up to 60 "
+                               "megapixels.")
+            image.seek(0)
+            image = ImageOps.exif_transpose(image)
+            width, height = image.size
+            if image.mode in ("RGBA", "LA", "P"):
+                rgba = image.convert("RGBA")
+                flat = Image.new("RGB", rgba.size, (255, 255, 255))
+                flat.paste(rgba, mask=rgba.split()[-1])
+                image = flat
+            else:
+                image = image.convert("RGB")
+            for name, size, quality in (("model.jpg", MODEL_PX, 85), ("thumb.jpg", THUMB_PX, 80)):
+                copy = image.copy()
+                copy.thumbnail((size, size))
+                _save_jpeg(copy, folder / name, quality)
+    except TooLarge:
+        raise
+    except Exception as error:  # noqa: BLE001 -- a damaged image is refused with a sentence
+        raise sniff.Unsupported(f"This image couldn't be opened ({type(error).__name__}). It may be damaged.") from None
+    return {"width": width, "height": height, "thumb": True, "model": True}
+
+
+def _save_jpeg(image, path, quality):
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW, 0o600)
+    with os.fdopen(fd, "wb") as handle:
+        image.save(handle, "JPEG", quality=quality, optimize=True)
+
+
+def sips_path():
+    return shutil.which("sips") or ("/usr/bin/sips" if Path("/usr/bin/sips").is_file() else None)
+
+
+def run_sips(argv, timeout=60):
+    return subprocess.run(argv, capture_output=True, timeout=timeout, stdin=subprocess.DEVNULL).returncode
+
+
+def _sips(original, folder):
+    """HEIC through macOS's own image tool (Pillow can't read HEIC): one full-size JPEG, then Pillow makes the two
+    pictures from it. sips keeps the photo's location; Pillow writes no metadata, so it never goes to the AI account."""
+    tool = sips_path()
+    if tool is None:
+        return {}
+    converted = folder / "heic-converted.jpg"
+    try:
+        try:
+            code = run_sips([tool, "-s", "format", "jpeg", "-s", "formatOptions", "92", str(original),
+                             "--out", str(converted)])
+        except (OSError, subprocess.SubprocessError):
+            code = 1
+        if code != 0 or converted.is_symlink() or not converted.is_file():
+            return {}
+        return _pillow(converted, folder)
+    finally:
+        try:
+            converted.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def pages_of(text):
+    """The pages of ``text.txt``: a PDF's pages (form feeds), else one page."""
+    return text.split(PAGE) if PAGE in text else [text]

mobile_agent/attachments/mcp.py

@@ -0,0 +1,104 @@
+"""The files track's MCP tools (seam S10): put_file, get_file and list_files, listed only when the server was started
+with ``mobster mcp --allow-files``."""
+
+import os
+from pathlib import Path
+
+from ..mcp_server.protocol import ToolResult
+from ..mcp_server.tools import ACTS, READ_ONLY, ToolError, jsonable, sentence
+from . import service
+
+WRITES_HERE = {"readOnlyHint": False, "destructiveHint": False, "idempotentHint": False, "openWorldHint": False}
+_DEVICE = {"type": "string", "minLength": 1, "maxLength": 128,
+           "description": "a USB iPhone from list_devices (its id or name)"}
+_APP = {"type": "string", "minLength": 3, "maxLength": 155, "pattern": "^[A-Za-z0-9][A-Za-z0-9.-]*$",
+        "description": "the app's bundle ID, such as com.apple.Pages (list_files lists the apps that share files)"}
+
+
+def _schema(properties, required=()):
+    return {"type": "object", "properties": properties, "required": list(required), "additionalProperties": False}
+
+
+class FilesTools:
+    name = "files"
+
+    def __init__(self, cwd=None):
+        self._cwd = cwd
+
+    def definitions(self, toolset):
+        return [
+            {"name": "put_file",
+             "description": "Copy a file from this Mac into an app's folder on a USB iPhone (the folder Files shows "
+                            "under On My iPhone), or a text file onto its clipboard. A file with the same name is "
+                            "kept; the copy gets a new name. At most 100 MB; never the camera roll.",
+             "inputSchema": _schema({"device": _DEVICE,
+                                     "path": {"type": "string", "minLength": 1, "maxLength": 1024,
+                                              "description": "the absolute path of the file on this Mac"},
+                                     "app": _APP,
+                                     "clipboard": {"type": "boolean",
+                                                   "description": "true: put a text file's text on the clipboard "
+                                                                  "instead (at most 64 KB)"}},
+                                    ("device", "path"))},
+            {"name": "get_file",
+             "description": "Copy a file from an app's folder on a USB iPhone to this Mac, into the server's working "
+                            "folder. Returns its path.",
+             "inputSchema": _schema({"device": _DEVICE, "app": _APP,
+                                     "name": {"type": "string", "minLength": 1, "maxLength": 255,
+                                              "description": "the file's name, from list_files"}},
+                                    ("device", "app", "name"))},
+            {"name": "list_files",
+             "description": "Without app: the iPhone's apps whose folders show in Files. With app: the files in "
+                            "that app's folder, with sizes.",
+             "inputSchema": _schema({"device": _DEVICE, "app": _APP}, ("device",))},
+        ]
+
+    def annotations(self):
+        return {"put_file": ACTS, "get_file": WRITES_HERE, "list_files": READ_ONLY}
+
+    def instructions(self):
+        """None: the server's instructions don't change (the tools are listed only with --allow-files, and their
+        descriptions say what they do)."""
+        return None
+
+    def call(self, name, arguments, call, toolset):
+        from ..phone_io import PhoneIOError
+        record = toolset._record_for(arguments)
+        try:
+            if name == "put_file":
+                return self._put(record, arguments, call, toolset)
+            phone = service.phone_files(record)
+            if name == "list_files":
+                if not arguments.get("app"):
+                    apps = phone.apps()
+                    words = ", ".join(f"{a['name']} ({a['bundleId']})" for a in apps) or "none"
+                    return ToolResult(f"Apps on {record['name']} whose folders show in Files: {words}.",
+                                      jsonable({"device": record["id"], "apps": apps}))
+                files = phone.ls(arguments["app"])
+                words = ", ".join(f"{f['name']}{'/' if f['folder'] else ''}" for f in files) or "nothing"
+                return ToolResult(f"{arguments['app']}'s folder on {record['name']} holds: {words}.",
+                                  jsonable({"device": record["id"], "app": arguments["app"], "files": files}))
+            folder = Path(self._cwd or os.getcwd())
+            saved = phone.get(arguments["app"], arguments["name"], folder)
+            return ToolResult(f"Saved {arguments['name']} from {record['name']} to {saved}.",
+                              jsonable({"device": record["id"], "path": str(saved), "bytes": saved.stat().st_size}))
+        except PhoneIOError as error:
+            raise ToolError(sentence(error) + (" " + sentence(error.fix) if error.fix else "")) from None
+
+    def _put(self, record, arguments, call, toolset):
+        path = Path(os.path.expanduser(arguments["path"]))
+        if not path.is_absolute():
+            raise ToolError("Pass the absolute path of the file on this Mac.")
+        clipboard, app = bool(arguments.get("clipboard")), arguments.get("app")
+        if clipboard == bool(app):
+            raise ToolError("Pass app (the bundle ID of the app whose folder takes it) or clipboard: true, not both.")
+        if clipboard:
+            from ..phone_io import PhoneIOError
+            from ..phone_io.clipboard import read_text_file
+            try:
+                text = read_text_file(path)
+            except PhoneIOError as error:
+                raise ToolError(sentence(error)) from None
+            return toolset.tool_set_clipboard({"device": arguments["device"], "text": text}, call)
+        result = service.phone_files(record).put(app, path)
+        return ToolResult(f"Put {result['name']} in {app}'s folder on {record['name']}. The Files app shows it under "
+                          "On My iPhone.", jsonable({"device": record["id"], **result}))

mobile_agent/attachments/register.py

@@ -0,0 +1,73 @@
+"""Track `files`'s registrations (tracks.load calls ``register(api)`` once per process, staged: a register that raises
+leaves nothing registered and is shown in GET /api/status "extensions")."""
+
+PENDING = "uploading"
+
+
+def validate_attachment_ids(value, runtime):
+    """``attachmentIds``: a list of at most 10 distinct attachment ids that exist here. ValueError otherwise."""
+    from . import service
+    from .store import PER_RUN
+    if value is None:
+        return []
+    if not isinstance(value, (list, tuple)):
+        raise ValueError("attachmentIds must be a list of file ids")
+    if PENDING in value:
+        raise ValueError("A file is still uploading. Run the task again when it's ready.")
+    if len(value) > PER_RUN:
+        raise ValueError(f"Attach at most {PER_RUN} files to a task.")
+    from .store import ID
+    ids = []
+    for item in value:
+        if not isinstance(item, str) or not ID.fullmatch(item):
+            raise ValueError("attachmentIds must be a list of file ids")
+        if item not in ids:
+            ids.append(item)
+    if not ids:
+        return []
+    store = service.store_for(runtime)
+    if store is None:
+        raise ValueError("Attaching files needs Mobster's data folder.")
+    found = {a.id for a in store.many(ids)}
+    if len(found) != len(ids):
+        raise ValueError("A file attached to this task is gone. Attach it again.")
+    return ids
+
+
+def register(api):
+    """``api`` is mobile_agent.harness_api."""
+    from .. import api_routes, journal
+    from ..mcp_server import registry as mcp_registry
+    from . import service, store
+    from .agent import AttachmentsProvider, PutFile, ReadAttachment
+    from .mcp import FilesTools
+    from .routes import ROUTES
+
+    journal.register_schema(store.SCHEMA, store.VERSION, store.migrate)
+    api.register_run_field("attachmentIds", validate_attachment_ids, public=True)
+
+    def files_store(ctx):
+        if not ctx.extras.get("attachmentIds"):
+            return None
+        return service.store_for(ctx.runtime)
+
+    def provider(ctx):
+        found = files_store(ctx)
+        return AttachmentsProvider(found) if found is not None else None
+
+    def read_tool(ctx):
+        found = files_store(ctx)
+        return ReadAttachment(found, ctx) if found is not None else None
+
+    def put_tool(ctx):
+        found = files_store(ctx)
+        return PutFile(found, ctx) if found is not None else None
+
+    # No run listener: one starts the core's listener thread for every run; the provider records use as it reads.
+    api.register_context_provider(provider, order=30)
+    api.register_tool(read_tool, order=30)
+    api.register_tool(put_tool, order=31)
+    api.register_service(service.start, service.close)
+    for route in ROUTES:
+        api_routes.register(route)
+    mcp_registry.register_provider(FilesTools())