kiwimatecoder 0.1.0__py3-none-any.whl

kiwimatecoder/tools/image.py

@@ -0,0 +1,300 @@
+"""Image tools: attach an image to the conversation, or generate media.
+
+``view_image`` attaches an existing workspace file (read-only). The
+``generate_image`` and ``generate_video`` tools call the configured media
+provider, which costs money, so they are approval-gated (``runs=True``) and
+refuse with enable guidance while media generation is turned off.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+from kiwimatecoder import config, images, media
+from kiwimatecoder.redaction import redact
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+from kiwimatecoder.tools.paths import PathError, display_path, resolve_for_read
+
+
+def _view_image(args: dict[str, Any], session: Session) -> ToolResult:
+    path = str(args.get("path") or "").strip()
+    if not path:
+        return ToolResult.error("'path' is required")
+    try:
+        resolved = resolve_for_read(
+            path,
+            session.workspace_root,
+            trusted=bool(getattr(session, "trusted_workspace", False)),
+        )
+    except PathError as exc:
+        return ToolResult.error(str(exc))
+    if not resolved.is_file():
+        return ToolResult.error(f"File not found: {path}")
+
+    vision = config.get_vision()
+    limit = int(vision["max_images_per_turn"])
+    if len(session.pending_images) >= limit:
+        return ToolResult.error(
+            f"Image limit reached ({limit} per turn). Send these images first, "
+            "then attach more in the next message."
+        )
+
+    try:
+        entry = images.encode_image(resolved, int(vision["max_image_bytes"]))
+    except (ValueError, OSError) as exc:
+        return ToolResult.error(str(exc))
+
+    session.pending_images.append(entry)
+    dimensions = images.image_dimensions(base64.b64decode(entry["data"]))
+    label = f"{path} ({dimensions[0]}x{dimensions[1]})" if dimensions else path
+    return ToolResult(content=f"Attached {label}")
+
+
+view_image_tool = FunctionTool(
+    name="view_image",
+    description=(
+        "Attach an image file (.png, .jpg, .jpeg, .gif, .webp) from the "
+        "workspace so the model can see it. Read-only; the image is sent with "
+        "the next request. Use it for screenshots, diagrams, and design mockups."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Path to the image, relative to the workspace root.",
+            },
+        },
+        "required": ["path"],
+    },
+    func=_view_image,
+)
+
+
+def _generate_image(args: dict[str, Any], session: Session) -> ToolResult:
+    if not config.get_media()["enabled"]:
+        return ToolResult.error(
+            "Image generation is disabled. Enable it with "
+            "`/config media enable on` (or `config media enable on`)."
+        )
+    prompt = str(args.get("prompt") or "").strip()
+    if not prompt:
+        return ToolResult.error("'prompt' is required")
+    size = args.get("size")
+    model = args.get("model")
+    try:
+        result = media.generate_image(
+            prompt,
+            session=session,
+            size=str(size).strip() if size else None,
+            model=str(model).strip() if model else None,
+        )
+    except media.MediaError as exc:
+        return ToolResult.error(str(exc))
+    note = media.attach_result(result, session)
+    location = display_path(result.path, session.workspace_root)
+    content = (
+        f"Generated image saved to {location} ({result.bytes:,} bytes, "
+        f"model {result.model})"
+    )
+    if note:
+        content += f". {note}"
+    return ToolResult(content=content)
+
+
+def generate_image_preview(args: dict[str, Any], session: Session) -> str:
+    """Render the approval preview: provider, model, size, and prompt."""
+    del session
+    settings = config.get_media()
+    prompt = redact(str(args.get("prompt") or "")).strip()
+    if len(prompt) > 300:
+        prompt = prompt[:297] + "..."
+    model = str(args.get("model") or settings["model"]).strip() or "(none chosen)"
+    size = str(args.get("size") or settings["size"]).strip()
+    return (
+        f"Provider: {settings['provider']}\n"
+        f"Model: {model}\n"
+        f"Size: {size}\n"
+        f"Output: {settings['output_dir']}\n"
+        f"Prompt: {prompt or '(missing)'}\n\n"
+        "This calls a paid image API."
+    )
+
+
+generate_image_tool = FunctionTool(
+    name="generate_image",
+    description=(
+        "Generate an image from a text prompt through the configured media "
+        "provider and attach it to the conversation. Costs money and requires "
+        "media generation to be enabled (`/config media enable on`) and an "
+        "image model to be chosen (`/image model`). Use it for mockups, icons, "
+        "diagrams, and illustrations."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "prompt": {
+                "type": "string",
+                "description": "A detailed description of the image to generate.",
+            },
+            "size": {
+                "type": "string",
+                "description": "Image size as WxH (default: configured size).",
+            },
+            "model": {
+                "type": "string",
+                "description": "Image model override (default: configured model).",
+            },
+        },
+        "required": ["prompt"],
+    },
+    func=_generate_image,
+    runs=True,
+)
+
+
+def _generate_video(args: dict[str, Any], session: Session) -> ToolResult:
+    if not config.get_media()["enabled"]:
+        return ToolResult.error(
+            "Media generation is disabled. Enable it with "
+            "`/config media enable on` (or `config media enable on`)."
+        )
+    resume_id = str(args.get("resume_job_id") or "").strip()
+    prompt = str(args.get("prompt") or "").strip()
+    if not resume_id and not prompt:
+        return ToolResult.error("'prompt' is required (or 'resume_job_id')")
+
+    first_frame = None
+    frame_arg = str(args.get("first_frame") or "").strip()
+    if frame_arg and not resume_id:
+        try:
+            first_frame = resolve_for_read(
+                frame_arg,
+                session.workspace_root,
+                trusted=bool(getattr(session, "trusted_workspace", False)),
+            )
+        except PathError as exc:
+            return ToolResult.error(str(exc))
+        if not first_frame.is_file():
+            return ToolResult.error(f"File not found: {frame_arg}")
+
+    duration = args.get("duration")
+    size = args.get("size")
+    model = args.get("model")
+    try:
+        if resume_id:
+            result = media.resume_video(resume_id, session=session)
+        else:
+            result = media.generate_video(
+                prompt,
+                session=session,
+                model=str(model).strip() if model else None,
+                duration=int(duration) if duration not in (None, "") else None,
+                size=str(size).strip() if size else None,
+                first_frame=first_frame,
+            )
+    except (TypeError, ValueError):
+        return ToolResult.error("'duration' must be a whole number of seconds")
+    except media.MediaError as exc:
+        return ToolResult.error(str(exc))
+    location = display_path(result.path, session.workspace_root)
+    content = (
+        f"Generated video saved to {location} ({media.format_bytes(result.bytes)}, "
+        f"model {result.model}, job {result.job_id}"
+    )
+    if result.cost is not None:
+        content += f", cost ${result.cost:.2f}"
+    return ToolResult(content=content + ")")
+
+
+def generate_video_preview(args: dict[str, Any], session: Session) -> str:
+    """Render the approval preview: provider, model, length, size, and prompt."""
+    del session
+    settings = config.get_media()
+    resume_id = str(args.get("resume_job_id") or "").strip()
+    if resume_id:
+        return (
+            f"Provider: {settings['provider']}\n"
+            f"Resume video job: {resume_id}\n\n"
+            "This fetches a video job that was already started (and billed)."
+        )
+    prompt = redact(str(args.get("prompt") or "")).strip()
+    if len(prompt) > 300:
+        prompt = prompt[:297] + "..."
+    model = str(args.get("model") or settings["video_model"]).strip()
+    duration = args.get("duration") or settings["video_duration"]
+    size = str(args.get("size") or settings["video_size"] or "provider default").strip()
+    lines = [
+        f"Provider: {settings['provider']}",
+        f"Model: {model or '(none chosen)'}",
+        f"Length: {duration}s",
+        f"Size: {size}",
+    ]
+    if args.get("first_frame"):
+        lines.append(f"First frame: {args['first_frame']}")
+    lines += [
+        f"Output: {settings['output_dir']}",
+        f"Prompt: {prompt or '(missing)'}",
+        "",
+        "This calls a paid video API. Video is billed per second of footage "
+        "and a clip can cost anywhere from cents to several dollars; it may "
+        "take a few minutes to render.",
+    ]
+    return "\n".join(lines)
+
+
+generate_video_tool = FunctionTool(
+    name="generate_video",
+    description=(
+        "Generate a short video from a text prompt (optionally animating a "
+        "workspace image as the first frame) through the configured media "
+        "provider and save it under the media output directory. Slow (minutes) "
+        "and billed per second, so use it only when asked for a video. Requires "
+        "media generation to be enabled and a video model to be chosen "
+        "(`/video model`). If a job times out, call again "
+        "with its `resume_job_id` instead of regenerating."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "prompt": {
+                "type": "string",
+                "description": "A detailed description of the video to generate.",
+            },
+            "duration": {
+                "type": "integer",
+                "description": "Length in seconds (default: configured duration).",
+            },
+            "size": {
+                "type": "string",
+                "description": (
+                    "WxH (e.g. 1280x720) or a tier such as 720p "
+                    "(default: configured size, else the provider's default)."
+                ),
+            },
+            "model": {
+                "type": "string",
+                "description": "Video model override (default: configured model).",
+            },
+            "first_frame": {
+                "type": "string",
+                "description": (
+                    "Workspace path to an image to animate as the first frame "
+                    "(image-to-video)."
+                ),
+            },
+            "resume_job_id": {
+                "type": "string",
+                "description": (
+                    "Job id from an earlier timed-out call; fetches that job "
+                    "instead of starting (and paying for) a new one."
+                ),
+            },
+        },
+        "required": [],
+    },
+    func=_generate_video,
+    runs=True,
+)

kiwimatecoder/tools/io.py

@@ -0,0 +1,346 @@
+"""Clipboard and HTTP/API testing tools.
+
+``read_clipboard`` and ``http_get`` are read-only (safe in plan mode).
+``write_clipboard`` and ``http_request`` execute a clipboard command or can
+mutate remote state, so they set ``runs=True`` and go through the approval
+gate. HTTP responses are rendered with a status line, selected headers, and a
+truncated body; raw ``httpx`` errors are never leaked.
+"""
+
+from __future__ import annotations
+
+import json as json_module
+from typing import Any
+
+import httpx
+
+from kiwimatecoder import clipboard as clipboard_module
+from kiwimatecoder import config
+from kiwimatecoder import web as web_module
+from kiwimatecoder.redaction import redact
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+
+HTTP_METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE")
+_PREVIEW_CHARS = 200
+_RESPONSE_HEADER_NAMES = (
+    "content-type",
+    "content-length",
+    "location",
+    "server",
+    "date",
+    "etag",
+    "last-modified",
+    "cache-control",
+    "www-authenticate",
+    "x-request-id",
+)
+
+
+def request_http(
+    method: str,
+    url: str,
+    *,
+    headers: dict[str, str] | None = None,
+    body: str | None = None,
+    json_body: Any = None,
+    timeout: float,
+    max_chars: int,
+    allow_local: bool,
+    transport: httpx.BaseTransport | None = None,
+) -> ToolResult:
+    """Perform an HTTP request and render a bounded, model-friendly result.
+
+    The response status is returned as-is (4xx/5xx are informative for API
+    testing), the body is clipped to ``max_chars``, and JSON payloads are
+    pretty-printed. ``transport`` exists for tests.
+    """
+    method = str(method).strip().upper()
+    if method not in HTTP_METHODS:
+        return ToolResult.error(
+            f"Unknown HTTP method '{method}'. Choose: {', '.join(HTTP_METHODS)}."
+        )
+    if body is not None and json_body is not None:
+        return ToolResult.error("'body' and 'json' are mutually exclusive")
+    try:
+        cleaned = web_module.clean_url(url)
+    except web_module.WebError as exc:
+        return ToolResult.error(str(exc))
+    if web_module.is_local_address(cleaned) and not allow_local:
+        return ToolResult.error(
+            "Refusing to call a local or private address. Enable it with "
+            "/config web allow-local on (or config web allow-local on)."
+        )
+
+    request_headers = {"User-Agent": web_module.USER_AGENT}
+    request_headers.update(headers or {})
+
+    byte_cap = max(1024, int(max_chars) * web_module.MAX_BYTES_PER_CHAR)
+    status_line = "HTTP ?"
+    final_url = cleaned
+    response_headers: dict[str, str] = {}
+    data = bytearray()
+    charset = "utf-8"
+    try:
+        with httpx.Client(
+            timeout=timeout, transport=transport, follow_redirects=True
+        ) as client:
+            with client.stream(
+                method,
+                cleaned,
+                headers=request_headers,
+                content=body,
+                json=json_body,
+            ) as response:
+                status_line = (
+                    f"HTTP {response.status_code} {response.reason_phrase}"
+                ).strip()
+                final_url = str(response.url)
+                response_headers = {
+                    key.lower(): value for key, value in response.headers.items()
+                }
+                charset = response.charset_encoding or "utf-8"
+                for chunk in response.iter_bytes():
+                    data.extend(chunk)
+                    if len(data) >= byte_cap:
+                        del data[byte_cap:]
+                        break
+    except httpx.HTTPError as exc:
+        return ToolResult.error(f"Request failed: {exc.__class__.__name__}.")
+
+    text = bytes(data).decode(charset, errors="replace")
+    mime = (response_headers.get("content-type") or "").split(";", 1)[0].strip().lower()
+    if mime == "application/json" or mime.endswith("+json"):
+        try:
+            text = json_module.dumps(
+                json_module.loads(text), indent=2, ensure_ascii=False
+            )
+        except (json_module.JSONDecodeError, ValueError):
+            pass
+    if len(text) > max_chars:
+        text = text[:max_chars] + f"\n\n[truncated at {max_chars} characters]"
+
+    lines = [status_line]
+    if final_url != cleaned:
+        lines.append(f"URL: {final_url}")
+    lines.extend(
+        f"{name}: {response_headers[name]}"
+        for name in _RESPONSE_HEADER_NAMES
+        if name in response_headers
+    )
+    rendered = "\n".join(lines)
+    if text:
+        rendered += "\n\n" + text
+    return ToolResult(content=rendered)
+
+
+def _string_headers(raw: Any) -> tuple[dict[str, str] | None, str | None]:
+    if raw is None:
+        return {}, None
+    if not isinstance(raw, dict):
+        return None, "'headers' must be an object of string values"
+    return {str(key): str(value) for key, value in raw.items()}, None
+
+
+def _http_call(
+    args: dict[str, Any], session: Session, *, method: str | None = None
+) -> ToolResult:
+    del session
+    url = str(args.get("url") or "").strip()
+    if not url:
+        return ToolResult.error("'url' is required")
+    headers, error = _string_headers(args.get("headers"))
+    if error:
+        return ToolResult.error(error)
+
+    settings = config.get_web()
+    timeout = float(settings["timeout"])
+    raw_timeout = args.get("timeout")
+    if raw_timeout is not None:
+        try:
+            timeout = float(raw_timeout)
+        except (TypeError, ValueError):
+            return ToolResult.error("'timeout' must be a number of seconds")
+        if not config.WEB_TIMEOUT_MIN <= timeout <= config.WEB_TIMEOUT_MAX:
+            return ToolResult.error(
+                f"'timeout' must be between {config.WEB_TIMEOUT_MIN:g} and "
+                f"{config.WEB_TIMEOUT_MAX:g} seconds"
+            )
+
+    body = args.get("body")
+    if body is not None and not isinstance(body, str):
+        return ToolResult.error("'body' must be a string")
+    json_body = args.get("json")
+    if body is not None and json_body is not None:
+        return ToolResult.error("'body' and 'json' are mutually exclusive")
+
+    chosen = method or str(args.get("method") or "").strip()
+    return request_http(
+        chosen,
+        url,
+        headers=headers,
+        body=body,
+        json_body=json_body,
+        timeout=timeout,
+        max_chars=int(settings["max_chars"]),
+        allow_local=bool(settings["allow_local"]),
+    )
+
+
+def _read_clipboard(args: dict[str, Any], session: Session) -> ToolResult:
+    del args, session
+    ok, payload = clipboard_module.read_clipboard()
+    if not ok:
+        return ToolResult.error(payload)
+    return ToolResult(content=payload if payload else "(clipboard is empty)")
+
+
+def _write_clipboard(args: dict[str, Any], session: Session) -> ToolResult:
+    del session
+    text = args.get("text")
+    if text is None or str(text) == "":
+        return ToolResult.error("'text' is required")
+    ok, message = clipboard_module.write_clipboard(str(text))
+    if not ok:
+        return ToolResult.error(message)
+    return ToolResult(content=message)
+
+
+def _clip(text: str) -> str:
+    return text if len(text) <= _PREVIEW_CHARS else text[:_PREVIEW_CHARS] + "…"
+
+
+def write_clipboard_preview(args: dict[str, Any], session: Session) -> str:
+    """Show (redacted, clipped) text for the write_clipboard approval prompt."""
+    del session
+    return f"Copy to clipboard:\n{_clip(redact(str(args.get('text') or ''))) or '(empty)'}"
+
+
+def http_request_preview(args: dict[str, Any], session: Session) -> str:
+    """Show the redacted request for the http_request approval prompt."""
+    del session
+    method = str(args.get("method") or "GET").strip().upper()
+    lines = [f"{method} {str(args.get('url') or '')}"]
+    headers = args.get("headers")
+    if isinstance(headers, dict):
+        lines.extend(f"{key}: {redact(str(value))}" for key, value in headers.items())
+    body = args.get("body")
+    json_body = args.get("json")
+    if body is not None:
+        lines.append(_clip(redact(str(body))))
+    elif json_body is not None:
+        try:
+            payload = json_module.dumps(json_body, ensure_ascii=False)
+        except (TypeError, ValueError):
+            payload = str(json_body)
+        lines.append(_clip(redact(payload)))
+    return "\n".join(lines)
+
+
+def _http_get(args: dict[str, Any], session: Session) -> ToolResult:
+    return _http_call(args, session, method="GET")
+
+
+def _http_request(args: dict[str, Any], session: Session) -> ToolResult:
+    return _http_call(args, session)
+
+
+read_clipboard_tool = FunctionTool(
+    name="read_clipboard",
+    description=(
+        "Read the system clipboard as text. Read-only, so it runs without "
+        "approval and stays available in plan mode."
+    ),
+    parameters={"type": "object", "properties": {}},
+    func=_read_clipboard,
+)
+
+write_clipboard_tool = FunctionTool(
+    name="write_clipboard",
+    description=(
+        "Copy text to the system clipboard. Requires approval; the preview "
+        "shows the exact text that will be copied."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "text": {
+                "type": "string",
+                "description": "Text to place on the clipboard.",
+            },
+        },
+        "required": ["text"],
+    },
+    func=_write_clipboard,
+    runs=True,
+)
+
+http_get_tool = FunctionTool(
+    name="http_get",
+    description=(
+        "Fetch an http(s) URL and return its status line, selected response "
+        "headers, and body (JSON is pretty-printed). Read-only. Local and "
+        "private addresses are blocked unless enabled in /config web; for "
+        "other methods use http_request."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "url": {
+                "type": "string",
+                "description": "Absolute http(s) URL to request.",
+            },
+            "headers": {
+                "type": "object",
+                "description": "Optional request headers (name -> value).",
+                "additionalProperties": {"type": "string"},
+            },
+        },
+        "required": ["url"],
+    },
+    func=_http_get,
+)
+
+http_request_tool = FunctionTool(
+    name="http_request",
+    description=(
+        "Send an HTTP request with GET, POST, PUT, PATCH, or DELETE and return "
+        "the status line, selected response headers, and body (JSON is "
+        "pretty-printed). Requires approval because it can change remote state. "
+        "Use 'body' for raw text or 'json' for a JSON payload, not both. Local "
+        "and private addresses are blocked unless enabled in /config web."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "method": {
+                "type": "string",
+                "enum": list(HTTP_METHODS),
+                "description": "HTTP method.",
+            },
+            "url": {
+                "type": "string",
+                "description": "Absolute http(s) URL to request.",
+            },
+            "headers": {
+                "type": "object",
+                "description": "Optional request headers (name -> value).",
+                "additionalProperties": {"type": "string"},
+            },
+            "body": {
+                "type": "string",
+                "description": "Raw request body (mutually exclusive with json).",
+            },
+            "json": {
+                "description": "JSON request body (mutually exclusive with body).",
+            },
+            "timeout": {
+                "type": "number",
+                "description": "Seconds before the request times out (default: configured).",
+            },
+        },
+        "required": ["method", "url"],
+    },
+    func=_http_request,
+    runs=True,
+)