agent-core-webcam 0.8.2__py3-none-any.whl

agent_core_webcam/__init__.py

@@ -0,0 +1 @@
+"""agent-core-webcam — Webcam capture endpoint for agent_core."""

agent_core_webcam/audit.py

@@ -0,0 +1,50 @@
+"""Append-only JSONL audit log for webcam tool invocations.
+
+Each ``capture_webcam_frame`` and ``list_cameras`` call writes one line.
+Schema is documented in the design spec. Failures are swallowed so an
+audit failure never breaks a capture.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from agent_core.audit import JsonlAuditLog
+
+
+@dataclass(frozen=True)
+class AuditEvent:
+    """One line in the webcam audit log."""
+
+    timestamp: datetime
+    tool: str
+    result: str  # "ok" | "error"
+    data: dict[str, Any]
+
+
+class AuditLog(JsonlAuditLog[AuditEvent]):
+    """Append-only JSONL audit log."""
+
+    def __init__(self, path: Path) -> None:
+        super().__init__(path)
+
+    @staticmethod
+    def default_path(endpoint_name: str) -> Path:
+        """Returns ``~/.agent-core/webcam/<endpoint_name>/audit.jsonl``."""
+        return Path.home() / ".agent-core" / "webcam" / endpoint_name / "audit.jsonl"
+
+    def _serialize(self, event: AuditEvent) -> str:
+        payload = {
+            "timestamp": event.timestamp.isoformat(),
+            "tool": event.tool,
+            "result": event.result,
+            "data": event.data,
+        }
+        return json.dumps(payload, default=str, ensure_ascii=False)
+
+
+__all__ = ["AuditEvent", "AuditLog"]

agent_core_webcam/endpoint.py

@@ -0,0 +1,419 @@
+"""WebcamEndpoint — bus endpoint that exposes capture tools via MCP.
+
+Implements the standard Endpoint protocol but ``deliver`` is a no-op:
+webcam is tool-only, no inbox, no agent-to-agent envelopes. The
+endpoint exists so MCP tools have somewhere to live and config to read.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from agent_core_webcam.audit import AuditEvent, AuditLog
+from agent_core_webcam.protocol import (
+    CameraBackend,
+    CameraBusyError,
+    CameraNotFoundError,
+    ReadTimeoutError,
+)
+
+if TYPE_CHECKING:
+    from agent_core.bus.envelope import Envelope
+    from agent_core.bus.handle import BusHandle
+
+log = logging.getLogger(__name__)
+
+
+def _to_tuple(value: tuple[int, int] | list[int]) -> tuple[int, int]:
+    if isinstance(value, tuple):
+        if len(value) != 2:
+            raise ValueError(f"resolution must be [width, height], got {value!r}")
+        return value
+    if isinstance(value, list) and len(value) == 2:
+        return (int(value[0]), int(value[1]))
+    raise ValueError(f"resolution must be [width, height], got {value!r}")
+
+
+@dataclass(frozen=True)
+class CaptureSuccess:
+    """Successful capture result."""
+
+    png_bytes: bytes
+    file_path: Path | None
+    metadata: dict
+
+
+@dataclass(frozen=True)
+class CaptureError:
+    """Failed capture — message is the agent-readable string."""
+
+    message: str
+
+
+@dataclass(frozen=True)
+class ListCamerasSuccess:
+    """list_cameras_safe success."""
+
+    cameras: list  # list[CameraInfo] — avoid forward-ref import dance
+
+
+@dataclass(frozen=True)
+class ListCamerasError:
+    """list_cameras_safe failure — message is the agent-readable string."""
+
+    message: str
+
+
+class WebcamEndpoint:
+    """Tool-only bus endpoint backing the webcam MCP tool surface."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        captures_root: Path | str | None = None,
+        audit_log_path: Path | str | None = None,
+        default_camera_index: int = 0,
+        default_resolution: tuple[int, int] | list[int] = (1280, 720),
+        max_resolution: tuple[int, int] | list[int] = (3840, 2160),
+        capture_timeout_seconds: float = 3.0,
+        enabled: bool = True,
+        camera_backend: CameraBackend | None = None,
+    ):
+        self.name = name
+        self.captures_root = (
+            Path(captures_root)
+            if captures_root is not None
+            else Path.home() / ".agent-core" / "webcam" / name
+        )
+        audit_path = (
+            Path(audit_log_path)
+            if audit_log_path is not None
+            else self.captures_root / "audit.jsonl"
+        )
+        self.audit_log = AuditLog(audit_path)
+        self.default_camera_index = default_camera_index
+        self.default_resolution = _to_tuple(default_resolution)
+        self.max_resolution = _to_tuple(max_resolution)
+        self.capture_timeout_seconds = capture_timeout_seconds
+        self.enabled = enabled
+        if camera_backend is None:
+            from agent_core_webcam.opencv_backend import OpenCVCameraBackend
+            camera_backend = OpenCVCameraBackend(timeout_seconds=capture_timeout_seconds)
+        self._backend: CameraBackend = camera_backend
+        self._handle: BusHandle | None = None
+        self._camera_locks: dict[int, asyncio.Lock] = {}
+        self._camera_locks_guard = asyncio.Lock()
+
+    async def start(self, bus: BusHandle) -> None:
+        self._handle = bus
+        log.info("WebcamEndpoint(name=%s) started; captures=%s", self.name, self.captures_root)
+
+    async def deliver(self, envelope: Envelope) -> None:
+        # Webcam is tool-only; envelopes addressed to us are unexpected.
+        # Log at debug, then ack so the bus doesn't redeliver or dead-letter.
+        log.debug(
+            "WebcamEndpoint(name=%s) ignoring delivered envelope %s", self.name, envelope.id
+        )
+        if self._handle is not None:
+            await self._handle.ack(envelope.id)
+
+    async def stop(self) -> None:
+        self._handle = None
+        log.info("WebcamEndpoint(name=%s) stopped", self.name)
+
+    async def _lock_for(self, camera_index: int) -> asyncio.Lock:
+        async with self._camera_locks_guard:
+            if camera_index not in self._camera_locks:
+                self._camera_locks[camera_index] = asyncio.Lock()
+            return self._camera_locks[camera_index]
+
+    async def capture_frame(
+        self,
+        *,
+        camera_index: int | None = None,
+        resolution: tuple[int, int] | list[int] | None = None,
+        save: bool = True,
+        note: str | None = None,
+    ) -> tuple[bytes, Path | None, dict]:
+        """Capture one frame; return (png_bytes, file_path, metadata).
+
+        Returns ``file_path=None`` when ``save=False``. Always appends an
+        audit entry. Errors raise — Task 7 maps them to user-facing
+        messages at the MCP boundary.
+        """
+        idx = camera_index if camera_index is not None else self.default_camera_index
+        res = _to_tuple(resolution) if resolution is not None else self.default_resolution
+        lock = await self._lock_for(idx)
+        async with lock:
+            # Enforce capture_timeout_seconds at the async layer: a hung
+            # backend read (OpenCV's cap.read() is uninterruptible) would
+            # otherwise hold this per-camera lock forever, wedging every future
+            # capture on this camera. wait_for releases the lock and surfaces a
+            # ReadTimeoutError; the orphaned worker thread is the lesser evil
+            # than a permanently-stuck endpoint.
+            try:
+                png_bytes = await asyncio.wait_for(
+                    asyncio.to_thread(self._backend.capture, idx, res),
+                    timeout=self.capture_timeout_seconds,
+                )
+            except TimeoutError as exc:
+                raise ReadTimeoutError(
+                    f"camera {idx} did not return a frame within "
+                    f"{self.capture_timeout_seconds}s"
+                ) from exc
+        timestamp = datetime.now(UTC).astimezone()
+        try:
+            all_cams = await asyncio.to_thread(self._backend.list_cameras)
+            cam_name = next((c.name for c in all_cams if c.index == idx), f"camera {idx}")
+        except Exception:
+            cam_name = f"camera {idx}"
+        file_path: Path | None = None
+        if save:
+            file_path = self.captures_root / timestamp.strftime("%Y-%m-%d") / (
+                timestamp.strftime("%H%M%S-") + f"{timestamp.microsecond // 1000:03d}.png"
+            )
+            await asyncio.to_thread(self._write_png, file_path, png_bytes)
+        meta = {
+            "camera_index": idx,
+            "camera_name": cam_name,
+            "resolution": res,
+            "timestamp": timestamp.isoformat(),
+            "filesize": len(png_bytes),
+            "file_path": str(file_path) if file_path else None,
+        }
+        await self.audit_log.write(
+            AuditEvent(
+                timestamp=timestamp,
+                tool="capture_webcam_frame",
+                result="ok",
+                data={
+                    "camera_index": idx,
+                    "camera_name": cam_name,
+                    "resolution": list(res),
+                    "save": save,
+                    "note": note,
+                    "file_path": str(file_path) if file_path else None,
+                    "filesize": len(png_bytes),
+                },
+            )
+        )
+        return png_bytes, file_path, meta
+
+    async def capture_frame_safe(
+        self,
+        *,
+        camera_index: int | None = None,
+        resolution: tuple[int, int] | list[int] | None = None,
+        save: bool = True,
+        note: str | None = None,
+    ) -> CaptureSuccess | CaptureError:
+        """Like ``capture_frame`` but maps every error to a CaptureError + audit.
+
+        The MCP tool wrapper uses this — it never wants to raise into FastMCP.
+        """
+        if not self.enabled:
+            return await self._error(
+                user_message=(
+                    "error: webcam endpoint is disabled (enabled=false in config). "
+                    "Ask the operator if this is unexpected."
+                ),
+                audit_error="endpoint disabled",
+                camera_index=camera_index,
+                resolution=_to_tuple(resolution) if resolution is not None else None,
+                save=save,
+                note=note,
+            )
+
+        # Resolution validation + cap.
+        idx = camera_index if camera_index is not None else self.default_camera_index
+        try:
+            res = _to_tuple(resolution) if resolution is not None else self.default_resolution
+        except ValueError as exc:
+            return await self._error(
+                user_message=(
+                    f"error: invalid resolution: {exc}. "
+                    f"Expected [width, height] (a list of two ints)."
+                ),
+                audit_error=f"invalid resolution: {exc}",
+                camera_index=idx,
+                save=save,
+                note=note,
+            )
+        if res[0] > self.max_resolution[0] or res[1] > self.max_resolution[1]:
+            return await self._error(
+                user_message=(
+                    f"error: requested resolution {res[0]}x{res[1]} exceeds "
+                    f"configured max {self.max_resolution[0]}x{self.max_resolution[1]}."
+                ),
+                audit_error="resolution capped",
+                camera_index=idx,
+                resolution=res,
+                save=save,
+                note=note,
+            )
+
+        try:
+            png_bytes, file_path, meta = await self.capture_frame(
+                camera_index=idx,
+                resolution=res,
+                save=save,
+                note=note,
+            )
+        except CameraNotFoundError:
+            try:
+                cams = await asyncio.to_thread(self._backend.list_cameras)
+                available = [c.index for c in cams]
+            except Exception:
+                available = []
+            return await self._error(
+                user_message=(
+                    f"error: no camera at index {idx} "
+                    f"(host has {len(available)} cameras: indices {available}). "
+                    f"Call list_cameras to see what's available."
+                ),
+                audit_error=f"camera {idx} not found",
+                camera_index=idx,
+                resolution=res,
+                save=save,
+                note=note,
+            )
+        except CameraBusyError:
+            try:
+                cams = await asyncio.to_thread(self._backend.list_cameras)
+                cam_name = next(
+                    (c.name for c in cams if c.index == idx),
+                    f"camera {idx}",
+                )
+            except Exception:
+                cam_name = f"camera {idx}"
+            return await self._error(
+                user_message=(
+                    f"error: camera {idx} ({cam_name}) is busy. "
+                    f"Likely in use by another application (Zoom, browser, etc.). "
+                    f"Try again in a moment."
+                ),
+                audit_error="camera busy",
+                camera_index=idx,
+                resolution=res,
+                save=save,
+                note=note,
+            )
+        except ReadTimeoutError:
+            return await self._error(
+                user_message=(
+                    f"error: camera opened but returned no frame within "
+                    f"{self.capture_timeout_seconds}s. Camera may be initializing or obstructed."
+                ),
+                audit_error="read timeout",
+                camera_index=idx,
+                resolution=res,
+                save=save,
+                note=note,
+            )
+        except OSError as exc:
+            return await self._error(
+                user_message=(
+                    f"error: capture succeeded but failed to write to disk: {exc}. "
+                    f"Image is unavailable; retry or set save=false."
+                ),
+                audit_error=f"disk write failed: {exc}",
+                camera_index=idx,
+                resolution=res,
+                save=save,
+                note=note,
+            )
+        return CaptureSuccess(png_bytes=png_bytes, file_path=file_path, metadata=meta)
+
+    async def list_cameras_safe(self) -> ListCamerasSuccess | ListCamerasError:
+        """Enumerate cameras, return list with audit. Best-effort — never raises."""
+        if not self.enabled:
+            timestamp = datetime.now(UTC).astimezone()
+            await self.audit_log.write(
+                AuditEvent(
+                    timestamp=timestamp,
+                    tool="list_cameras",
+                    result="error",
+                    data={"error": "endpoint disabled"},
+                )
+            )
+            return ListCamerasError(
+                message=(
+                    "error: webcam endpoint is disabled (enabled=false in config). "
+                    "Ask the operator if this is unexpected."
+                )
+            )
+        try:
+            cams = await asyncio.to_thread(self._backend.list_cameras)
+        except Exception as exc:
+            timestamp = datetime.now(UTC).astimezone()
+            await self.audit_log.write(
+                AuditEvent(
+                    timestamp=timestamp,
+                    tool="list_cameras",
+                    result="error",
+                    data={"error": f"backend list_cameras failed: {exc}"},
+                )
+            )
+            return ListCamerasError(
+                message=(
+                    f"error: failed to enumerate cameras: {exc}. "
+                    f"Check that the camera driver is responsive."
+                )
+            )
+        timestamp = datetime.now(UTC).astimezone()
+        await self.audit_log.write(
+            AuditEvent(
+                timestamp=timestamp,
+                tool="list_cameras",
+                result="ok",
+                data={"camera_count": len(cams)},
+            )
+        )
+        return ListCamerasSuccess(cameras=list(cams))
+
+    async def _error(
+        self,
+        *,
+        user_message: str,
+        audit_error: str,
+        camera_index: int | None = None,
+        resolution: tuple[int, int] | None = None,
+        save: bool = True,
+        note: str | None = None,
+    ) -> CaptureError:
+        timestamp = datetime.now(UTC).astimezone()
+        await self.audit_log.write(
+            AuditEvent(
+                timestamp=timestamp,
+                tool="capture_webcam_frame",
+                result="error",
+                data={
+                    "camera_index": camera_index,
+                    "resolution": list(resolution) if resolution else None,
+                    "save": save,
+                    "note": note,
+                    "error": audit_error,
+                },
+            )
+        )
+        return CaptureError(message=user_message)
+
+    @staticmethod
+    def _write_png(path: Path, data: bytes) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(data)
+
+
+__all__ = [
+    "CaptureError",
+    "CaptureSuccess",
+    "ListCamerasError",
+    "ListCamerasSuccess",
+    "WebcamEndpoint",
+]

agent_core_webcam/fake.py

@@ -0,0 +1,142 @@
+"""Deterministic camera backend for tests.
+
+Mirrors ``OpenCVCameraBackend``'s behavior strictly — including refusing
+argument shapes the real backend refuses (unknown camera index →
+``CameraNotFoundError``). Produces minimal valid PNGs without any
+imaging work, so tests stay fast.
+"""
+
+from __future__ import annotations
+
+import struct
+import zlib
+from dataclasses import dataclass, field
+from typing import Any
+
+from agent_core_webcam.protocol import (
+    CameraBusyError,
+    CameraInfo,
+    CameraNotFoundError,
+    ReadTimeoutError,
+)
+
+
+class _FluentMode:
+    """Descriptor that makes a mode-setter work both as a classmethod
+    (``FakeCameraBackend.with_busy(0)`` creates a fresh instance) and as
+    an instance method (``fake.with_busy(0)`` mutates + returns the
+    existing instance), so call-chains like
+    ``FakeCameraBackend.with_cameras([0,1]).with_busy(0)`` compose
+    correctly.
+    """
+
+    def __init__(self, attr: str) -> None:
+        self._attr = attr
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self._name = name
+
+    def __get__(self, obj: Any, objtype: type | None = None) -> Any:
+        attr = self._attr
+
+        if obj is None:
+            # Called on the class: FakeCameraBackend.with_busy(0)
+            def class_call(index: int) -> FakeCameraBackend:
+                inst = FakeCameraBackend()
+                getattr(inst, attr).add(index)
+                return inst
+
+            return class_call
+        else:
+            # Called on an instance: fake.with_busy(0)
+            def instance_call(index: int) -> FakeCameraBackend:
+                getattr(obj, attr).add(index)
+                return obj
+
+            return instance_call
+
+
+@dataclass
+class FakeCameraBackend:
+    """In-memory camera backend with composable failure modes.
+
+    Use the classmethods (``with_cameras``, ``with_busy``, etc.) to
+    configure modes. Each returns a new or existing ``FakeCameraBackend``
+    so test setup reads naturally.
+    """
+
+    available_indices: list[int] = field(default_factory=lambda: [0])
+    _busy: set[int] = field(default_factory=set)
+    _missing: set[int] = field(default_factory=set)
+    _timeout: set[int] = field(default_factory=set)
+
+    @classmethod
+    def with_cameras(cls, indices: list[int]) -> FakeCameraBackend:
+        return cls(available_indices=list(indices))
+
+    # Each _FluentMode below must have a matching `set[int]` field in the dataclass.
+    # Adding a new `with_X = _FluentMode("_X")` without also declaring
+    # `_X: set[int] = field(default_factory=set)` above will raise AttributeError
+    # on first use.
+    with_busy = _FluentMode("_busy")
+    with_missing = _FluentMode("_missing")
+    with_read_timeout = _FluentMode("_timeout")
+
+    def list_cameras(self) -> list[CameraInfo]:
+        """List available cameras with their status.
+
+        Cameras marked `with_missing(idx)` where idx is NOT in `available_indices`
+        are NOT enumerated — "missing" means "this index doesn't exist on the host,"
+        so the fake mirrors real OpenCV's silence about indices it cannot open.
+        Cameras marked `with_busy(idx)` where idx IS in `available_indices` DO
+        appear in the list with `available=False` — "busy" means "exists but currently
+        in use elsewhere."
+        """
+        out: list[CameraInfo] = []
+        for idx in self.available_indices:
+            available = idx not in self._busy and idx not in self._missing
+            out.append(CameraInfo(index=idx, name=f"Fake Camera {idx}", available=available))
+        return out
+
+    def capture(self, index: int, resolution: tuple[int, int]) -> bytes:
+        if index in self._missing:
+            raise CameraNotFoundError(f"camera {index} marked missing")
+        if index not in self.available_indices:
+            raise CameraNotFoundError(f"camera {index} not in configured indices")
+        if index in self._busy:
+            raise CameraBusyError(f"camera {index} is busy")
+        if index in self._timeout:
+            raise ReadTimeoutError(f"camera {index} did not return a frame in time")
+        return _make_minimal_png(resolution)
+
+
+def _make_minimal_png(resolution: tuple[int, int]) -> bytes:
+    """Produce a valid solid-gray PNG of the requested resolution.
+
+    Uses pure-Python PNG construction (no PIL/cv2 dependency) so the
+    fake stays light. The image is solid mid-gray RGB; tests only need
+    the bytes to be a valid PNG with the right dimensions.
+    """
+    width, height = resolution
+    # IHDR: width, height, bit depth=8, color type=2 (RGB), compression, filter, interlace
+    ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
+    raw = b""
+    row_bytes = width * 3
+    for _ in range(height):
+        raw += b"\x00" + (b"\x80" * row_bytes)  # filter byte + gray pixels
+    idat = zlib.compress(raw, 9)
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        + _png_chunk(b"IHDR", ihdr)
+        + _png_chunk(b"IDAT", idat)
+        + _png_chunk(b"IEND", b"")
+    )
+
+
+def _png_chunk(tag: bytes, data: bytes) -> bytes:
+    length = struct.pack(">I", len(data))
+    crc = struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF)
+    return length + tag + data + crc
+
+
+__all__ = ["FakeCameraBackend"]

agent_core_webcam/mcp.py

@@ -0,0 +1,96 @@
+"""Agent-facing MCP tool surface for the webcam endpoint.
+
+Two tools: ``capture_webcam_frame`` and ``list_cameras``. Each returns
+a list of MCP content blocks. On error, only TextContent is returned —
+no image. The endpoint's ``capture_frame_safe`` / ``list_cameras_safe``
+methods do the error mapping; this module just adapts the result type
+to MCP content blocks.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import TYPE_CHECKING, Any
+
+from mcp.types import ImageContent, TextContent
+
+from agent_core_webcam.endpoint import (
+    CaptureError,
+    CaptureSuccess,
+    ListCamerasError,
+    ListCamerasSuccess,
+)
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+    from agent_core_webcam.endpoint import WebcamEndpoint
+
+
+def register_webcam_tools(*, mcp: FastMCP, endpoint: WebcamEndpoint) -> None:
+    """Register the two webcam tools on a FastMCP server."""
+
+    @mcp.tool(
+        name="capture_webcam_frame",
+        description=(
+            "Capture a single frame from a connected webcam. Returns the image "
+            "inline (so you can see it immediately) plus a saved file path you "
+            "can later attach to a Discord message, archive, or revisit. Use "
+            "camera_index=0 for the default camera; call list_cameras to "
+            "enumerate other devices."
+        ),
+    )
+    async def _capture(
+        camera_index: int = 0,
+        resolution: list[int] | None = None,
+        save: bool = True,
+        note: str | None = None,
+    ) -> list[Any]:
+        """Capture one frame; return [ImageContent, TextContent] on success."""
+        result = await endpoint.capture_frame_safe(
+            camera_index=camera_index,
+            resolution=list(resolution) if resolution else None,
+            save=save,
+            note=note,
+        )
+        if isinstance(result, CaptureError):
+            return [TextContent(type="text", text=result.message)]
+        assert isinstance(result, CaptureSuccess)
+        meta = result.metadata
+        text = (
+            f"Captured frame from camera {meta['camera_index']} ({meta['camera_name']}) "
+            f"at {meta['resolution'][0]}x{meta['resolution'][1]}.\n"
+            f"Path: {meta['file_path']}\n"
+            f"Timestamp: {meta['timestamp']}\n"
+            f"Filesize: {meta['filesize']} bytes"
+        )
+        return [
+            ImageContent(
+                type="image",
+                data=base64.b64encode(result.png_bytes).decode("ascii"),
+                mimeType="image/png",
+            ),
+            TextContent(type="text", text=text),
+        ]
+
+    @mcp.tool(
+        name="list_cameras",
+        description=(
+            "List all webcams detected on this host. Use the returned `index` "
+            "as the `camera_index` argument to capture_webcam_frame."
+        ),
+    )
+    async def _list_cameras() -> list[Any]:
+        result = await endpoint.list_cameras_safe()
+        if isinstance(result, ListCamerasError):
+            return [TextContent(type="text", text=result.message)]
+        assert isinstance(result, ListCamerasSuccess)
+        payload = [
+            {"index": c.index, "name": c.name, "available": c.available}
+            for c in result.cameras
+        ]
+        return [TextContent(type="text", text=json.dumps(payload))]
+
+
+__all__ = ["register_webcam_tools"]

agent_core_webcam/opencv_backend.py

@@ -0,0 +1,107 @@
+"""Real-OpenCV CameraBackend.
+
+Imports cv2 lazily inside method bodies so test environments that inject
+a fake backend never need cv2 at module-import time. cv2's failure modes
+are mapped onto our protocol exception taxonomy.
+"""
+
+from __future__ import annotations
+
+from agent_core_webcam.protocol import (
+    CameraBackend,
+    CameraBusyError,
+    CameraInfo,
+    CameraNotFoundError,
+    WebcamError,
+)
+
+# Probe up to this many camera indices when listing. Most consumer hosts
+# have 0–2 cameras; 8 is a generous ceiling without making list_cameras
+# pay 100ms-each-failed-open across hundreds of indices.
+_MAX_PROBE_INDEX = 8
+
+
+class OpenCVCameraBackend:
+    """cv2-backed CameraBackend.
+
+    Open + release per call. No long-lived state — the OS hardware LED
+    reflects "agent is looking right now" honestly.
+    """
+
+    def __init__(self, *, timeout_seconds: float = 3.0):
+        self._timeout = timeout_seconds
+
+    def list_cameras(self) -> list[CameraInfo]:
+        import cv2  # lazy import so cv2 isn't required by importing this module
+
+        out: list[CameraInfo] = []
+        for idx in range(_MAX_PROBE_INDEX):
+            cap = cv2.VideoCapture(idx)
+            if cap is None:
+                continue
+            opened = cap.isOpened()
+            if not opened:
+                cap.release()
+                # No camera at this index — stop probing further indices.
+                # On Windows DirectShow, indices are dense from 0 upward.
+                if idx == 0:
+                    return []
+                break
+            name = self._best_effort_name(cap, idx)
+            cap.release()
+            out.append(CameraInfo(index=idx, name=name, available=True))
+        return out
+
+    @staticmethod
+    def _best_effort_name(cap, idx: int) -> str:
+        # cv2 doesn't expose device names cross-platform. On Windows
+        # CAP_DSHOW we could probe via WMI but that's a rabbit hole.
+        # Fall back to a generic label.
+        return f"Camera {idx}"
+
+    def capture(self, index: int, resolution: tuple[int, int]) -> bytes:
+        import cv2
+
+        cap = cv2.VideoCapture(index)
+        if cap is None or not cap.isOpened():
+            if cap is not None:
+                cap.release()
+            raise CameraNotFoundError(f"camera {index} could not be opened")
+        try:
+            cap.set(cv2.CAP_PROP_FRAME_WIDTH, resolution[0])
+            cap.set(cv2.CAP_PROP_FRAME_HEIGHT, resolution[1])
+            # Honor the timeout via cv2's own read; cv2 doesn't expose a
+            # blocking timeout per se, so we rely on cv2 returning False
+            # when no frame is available. A truly hung driver would
+            # require process-level handling — out of scope for v1.
+            ok, frame = cap.read()
+            if not ok or frame is None:
+                # On Windows, "device opened but read failed" most
+                # commonly means another process holds the video pin
+                # exclusively (Zoom, browser camera, etc.).
+                raise CameraBusyError(f"camera {index} opened but read failed")
+            # cv2.imencode expects a BGR array (cv2's in-memory convention) and
+            # writes RGB-ordered PNG bytes — i.e. it handles the channel swap
+            # internally. Do NOT pre-convert with cvtColor(BGR2RGB) — that
+            # produces a doubly-swapped PNG with R and B reversed.
+            #
+            # This was confirmed in two ways on 2026-05-06: (1) a synthetic test
+            # decoding raw IDAT bytes from a known-color test pattern, and
+            # (2) end-to-end Pepper captures shown to Jeff. The version WITHOUT
+            # cvtColor renders the room correctly (cool monitor light reflecting
+            # off neutral surfaces); the version WITH cvtColor adds an artificial
+            # yellow cast.
+            ok2, buf = cv2.imencode(".png", frame)
+            if not ok2:
+                raise WebcamError(f"camera {index} returned a frame but PNG encode failed")
+            return bytes(buf.tobytes())
+        finally:
+            cap.release()
+
+
+# Static protocol satisfaction check (running the constructor is fine —
+# cv2 is lazy-loaded inside method bodies).
+_: CameraBackend = OpenCVCameraBackend()
+
+
+__all__ = ["OpenCVCameraBackend"]

agent_core_webcam/plugin.py

@@ -0,0 +1,87 @@
+"""Agent_core entry-point hook surface for the webcam framework.
+
+Three hookimpls:
+
+* ``register_endpoint_types`` — exposes ``builtin.webcam`` so the bus
+  runner can construct a ``WebcamEndpoint`` from a yaml entry.
+* ``reserved_endpoint_params`` — declares ``webcam`` so the runner pops
+  it from claude_code_mcp's params before constructing.
+* ``wire_endpoints_after_registration`` — pairs every
+  ``ClaudeCodeMCPEndpoint`` whose yaml params name a webcam endpoint
+  with that endpoint instance, appending a deferred mounter that
+  registers the two webcam tools on the FastMCP server at
+  ``bus.start()`` time.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pluggy
+
+if TYPE_CHECKING:
+    from agent_core.bus.protocol import Endpoint
+    from agent_core.plugins.specs import RunnerServices
+
+hookimpl = pluggy.HookimplMarker("agent_core")
+
+
+@hookimpl
+def register_endpoint_types() -> dict[str, type[Any]]:
+    """Register ``builtin.webcam`` as a bus endpoint type."""
+    from agent_core_webcam.endpoint import WebcamEndpoint
+
+    return {"builtin.webcam": WebcamEndpoint}
+
+
+@hookimpl
+def reserved_endpoint_params() -> list[str]:
+    """The runner pops these keys from each endpoint's params before constructing."""
+    return ["webcam"]
+
+
+@hookimpl
+def wire_endpoints_after_registration(
+    endpoints: dict[str, Endpoint],
+    raw_endpoint_configs: dict[str, dict[str, Any]],
+    services: RunnerServices,
+) -> None:
+    """Mount webcam tools on every MCP endpoint that names a webcam endpoint."""
+    del services  # unused — kept for hookspec parity
+    from agent_core.endpoints.claude_code_mcp import ClaudeCodeMCPEndpoint
+    from agent_core_webcam.endpoint import WebcamEndpoint
+    from agent_core_webcam.mcp import register_webcam_tools
+
+    for name, endpoint in endpoints.items():
+        if not isinstance(endpoint, ClaudeCodeMCPEndpoint):
+            continue
+        raw = raw_endpoint_configs.get(name) or {}
+        params = raw.get("params") or {}
+        webcam_name = params.get("webcam")
+        if not webcam_name:
+            continue
+        webcam = endpoints.get(webcam_name)
+        if webcam is None:
+            available = sorted(n for n, e in endpoints.items() if isinstance(e, WebcamEndpoint))
+            raise ValueError(
+                f"endpoint {name!r} names webcam={webcam_name!r} but no endpoint with "
+                f"that name is registered. Available WebcamEndpoint names: {available}"
+            )
+        if not isinstance(webcam, WebcamEndpoint):
+            available = sorted(n for n, e in endpoints.items() if isinstance(e, WebcamEndpoint))
+            raise ValueError(
+                f"endpoint {name!r} names webcam={webcam_name!r}, but that endpoint is "
+                f"a {type(webcam).__name__}, not a WebcamEndpoint. "
+                f"Available WebcamEndpoint names: {available}"
+            )
+
+        def _mounter(
+            bus_handle,
+            *,
+            webcam: WebcamEndpoint = webcam,
+            mcp_endpoint: ClaudeCodeMCPEndpoint = endpoint,
+        ) -> None:
+            del bus_handle  # webcam tools don't publish onto the bus
+            register_webcam_tools(mcp=mcp_endpoint._mcp, endpoint=webcam)
+
+        endpoint.deferred_tool_mounters.append(_mounter)

agent_core_webcam/protocol.py

@@ -0,0 +1,67 @@
+"""Camera backend protocol + exception taxonomy.
+
+The ``CameraBackend`` Protocol is the seam that lets ``WebcamEndpoint``
+work against either ``OpenCVCameraBackend`` (real) or ``FakeCameraBackend``
+(deterministic for tests). All failure modes the endpoint maps to
+agent-readable error messages descend from ``WebcamError`` so the
+endpoint's exception handling stays simple.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+class WebcamError(Exception):
+    """Base for every error a CameraBackend may raise."""
+
+
+class CameraNotFoundError(WebcamError):
+    """The requested camera index does not exist on this host."""
+
+
+class CameraBusyError(WebcamError):
+    """The camera opened but is in use by another process."""
+
+
+class ReadTimeoutError(WebcamError):
+    """The camera opened but did not return a frame within the timeout."""
+
+
+@dataclass(frozen=True)
+class CameraInfo:
+    """One enumerated camera on the host."""
+
+    index: int
+    name: str
+    available: bool
+
+
+@runtime_checkable
+class CameraBackend(Protocol):
+    """Hardware-access seam used by WebcamEndpoint."""
+
+    def list_cameras(self) -> list[CameraInfo]:
+        """Enumerate cameras the host can see right now."""
+
+    def capture(self, index: int, resolution: tuple[int, int]) -> bytes:
+        """Capture one frame from camera ``index`` at ``resolution``.
+
+        Returns PNG-encoded bytes (sRGB, RGB-ordered).
+
+        Raises:
+            CameraNotFoundError: index not present on this host.
+            CameraBusyError: device opened but is in use elsewhere.
+            ReadTimeoutError: device opened but read() returned no frame.
+        """
+
+
+__all__ = [
+    "CameraBackend",
+    "CameraBusyError",
+    "CameraInfo",
+    "CameraNotFoundError",
+    "ReadTimeoutError",
+    "WebcamError",
+]

agent_core_webcam-0.8.2.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: agent-core-webcam
+Version: 0.8.2
+Summary: Webcam endpoint for agent_core — agent-driven on-demand frame capture
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: agent-core-bus<0.9,>=0.8
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: opencv-python>=5.0.0.93
+Requires-Dist: pluggy>=1.6
+Requires-Dist: pydantic>=2.7

agent_core_webcam-0.8.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+agent_core_webcam/__init__.py,sha256=chVcO0DtqtnE6qEGbvU11I7vIffzEhCdrkCrYqVeQIk,68
+agent_core_webcam/audit.py,sha256=i1fGHqWJNS1v_hE09O9MVzBlt51UICLEIb_cGUPyRJw,1372
+agent_core_webcam/endpoint.py,sha256=wS-TcNLo065ge1s27SJpMrDjwoMoUlCADY2rA-za1TE,15441
+agent_core_webcam/fake.py,sha256=gBRZfbbKvajaxBP2G_y2mfffPF0QMoiQoJj2NU-kMos,5224
+agent_core_webcam/mcp.py,sha256=7LhAdXfVB-I91YOBjW-tlviqaoAPTJin0SuuSir9ku4,3343
+agent_core_webcam/opencv_backend.py,sha256=FnKlZ9zAHs-fLrlYELAYfkaaspH6YkGCb7ar3QReEiI,4281
+agent_core_webcam/plugin.py,sha256=SxRWfJ2HqTGKrTXxQnTYjdIvesgGvvARE_pOlTV6tm0,3297
+agent_core_webcam/protocol.py,sha256=vbuIJ6pU2bpLrwx5866bgujKvgTOQNW2CSltuPcb4fU,1847
+agent_core_webcam-0.8.2.dist-info/METADATA,sha256=YsH_DKsMhSXuxzDLN3F7nnvC_PJWACzhnIY4zRHqgjU,353
+agent_core_webcam-0.8.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agent_core_webcam-0.8.2.dist-info/entry_points.txt,sha256=K8iIBlcP5gMp7FX_yCVeD5jTrQzS9E61SMK5924cpE4,55
+agent_core_webcam-0.8.2.dist-info/RECORD,,

agent_core_webcam-0.8.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_core_webcam-0.8.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[agent_core]
+webcam_aliases = agent_core_webcam.plugin