gl-computer-use-binary 0.0.1__cp313-cp313-win_amd64.whl

gl_computer_use/__init__.pyi

@@ -0,0 +1,7 @@
+from gl_computer_use.client import GLComputerUseClient as GLComputerUseClient
+from gl_computer_use.config import GLComputerUseConfig as GLComputerUseConfig
+from gl_computer_use.errors import AgentError as AgentError, ArtifactStoreError as ArtifactStoreError, ConfigError as ConfigError, DesktopError as DesktopError, GLComputerUseError as GLComputerUseError, GLConnectionError as GLConnectionError, GLTimeoutError as GLTimeoutError, ProviderMismatchError as ProviderMismatchError, ResumeError as ResumeError, SandboxError as SandboxError, SandboxProvisionError as SandboxProvisionError, SessionBusyError as SessionBusyError, SessionError as SessionError, SessionNotReadyError as SessionNotReadyError, SnapshotError as SnapshotError, TakeoverError as TakeoverError, TakeoverInProgressError as TakeoverInProgressError, TakeoverNotActiveError as TakeoverNotActiveError, TakeoverRequiredError as TakeoverRequiredError, TaskCancelledError as TaskCancelledError, TaskError as TaskError, TaskFailedError as TaskFailedError
+from gl_computer_use.registry import register_agent as register_agent, register_artifact as register_artifact, register_sandbox as register_sandbox
+from gl_computer_use.types import ActionDetail as ActionDetail, EventType as EventType, File as File, ResumeToken as ResumeToken, RunContext as RunContext, SandboxDisposition as SandboxDisposition, SessionState as SessionState, TakeoverContext as TakeoverContext, TakeoverResponse as TakeoverResponse, TakeoverState as TakeoverState, Task as Task, TaskEvent as TaskEvent, TaskResult as TaskResult
+
+__all__ = ['GLComputerUseClient', 'GLComputerUseConfig', 'TaskResult', 'TaskEvent', 'ActionDetail', 'EventType', 'RunContext', 'SessionState', 'File', 'Task', 'TakeoverContext', 'TakeoverResponse', 'TakeoverState', 'ResumeToken', 'SandboxDisposition', 'register_agent', 'register_sandbox', 'register_artifact', 'GLComputerUseError', 'ConfigError', 'SandboxError', 'SandboxProvisionError', 'SnapshotError', 'ResumeError', 'ProviderMismatchError', 'AgentError', 'DesktopError', 'TaskError', 'TaskFailedError', 'TaskCancelledError', 'TakeoverRequiredError', 'TakeoverError', 'TakeoverInProgressError', 'TakeoverNotActiveError', 'SessionError', 'SessionBusyError', 'SessionNotReadyError', 'ArtifactStoreError', 'GLConnectionError', 'GLTimeoutError']

gl_computer_use/_setup.pyi

@@ -0,0 +1,7 @@
+def install_browsers() -> None:
+    """Download Playwright Chromium browser binaries.
+
+    Invokes ``playwright install chromium`` using the current Python
+    interpreter's ``playwright`` entry point. Exits with a non-zero code if
+    the playwright package is not installed or the download fails.
+    """

gl_computer_use/_urls.pyi

@@ -0,0 +1,16 @@
+def split_scheme(value: str, default_scheme: str = 'http') -> tuple[str, str]:
+    """Split an endpoint into its scheme and bare host.
+
+    A scheme embedded in ``value`` always wins over ``default_scheme`` — an
+    endpoint written as ``https://host`` must never be downgraded by a stale
+    protocol setting.
+
+    Args:
+        value: Endpoint string, with or without a scheme (e.g. ``host:8080``
+            or ``https://host``).
+        default_scheme: Scheme to apply when ``value`` carries none.
+
+    Returns:
+        A ``(scheme, host)`` tuple. ``host`` never carries a scheme and never
+        has trailing slashes.
+    """

gl_computer_use/agent/_anthropic_usage.pyi

@@ -0,0 +1,20 @@
+from dataclasses import dataclass, field as field
+
+@dataclass
+class _Accum:
+    tokens_in: int = ...
+    tokens_out: int = ...
+    cache_creation: int = ...
+    cache_read: int = ...
+    cost: float = ...
+    cost_known: bool = ...
+
+def install() -> None:
+    """Monkey-patch gui_agents.s3.core.mllm to use the tracking engine.
+
+    Must patch the *mllm* namespace because ``mllm.py`` imports
+    ``LMMEngineAnthropic`` by name; patching the ``engine`` module attribute
+    is too late once ``mllm`` has been imported.
+
+    Idempotent — safe to call multiple times.
+    """

gl_computer_use/agent/_openai_usage.pyi

@@ -0,0 +1,9 @@
+def install() -> None:
+    """Monkey-patch gui_agents.s3.core.mllm to use the tracking OpenAI engine.
+
+    Must patch the *mllm* namespace because ``mllm.py`` imports
+    ``LMMEngineOpenAI`` by name; patching the ``engine`` module attribute is
+    too late once ``mllm`` has been imported.
+
+    Idempotent — safe to call multiple times.
+    """

gl_computer_use/agent/_takeover.pyi

@@ -0,0 +1,37 @@
+import re
+from gl_computer_use.types import RunContext as RunContext
+
+async def handle_takeover(ctx: RunContext, reason: str) -> None:
+    """Emit TAKEOVER_STARTED, block until resumed, then emit TAKEOVER_RESUMED.
+
+    Shared across agent implementations so they call this with identical
+    semantics. After this coroutine returns, noop_count is reset to 0 and
+    ctx.paused_event is cleared.
+
+    Args:
+        ctx: The current run context (resume_event will be cleared/awaited).
+        reason: One of AGENT_REQUESTED, POLICY_TRIGGERED, CALLER_INITIATED.
+    """
+
+class TakeoverPolicy:
+    """Tracks takeover-policy counters for one agent run.
+
+    Attributes:
+        steps_in_epoch: Real-decision steps since last max_steps takeover.
+        stuck_re: Compiled pattern for agent_stuck_patterns, or None.
+    """
+    steps_in_epoch: int
+    stuck_re: re.Pattern[str] | None
+    def __init__(self, stuck_patterns: list[str]) -> None:
+        """Initialise with the compiled stuck-detection regex.
+
+        Args:
+            stuck_patterns: List of lowercase substrings from
+                GLComputerUseConfig.stuck_patterns().
+        """
+    def is_stuck(self, text: str) -> bool:
+        """Return True if *text* matches any stuck-detection pattern.
+
+        Args:
+            text: Combined reasoning + message text from the current step.
+        """

gl_computer_use/agent/agent_s.pyi

@@ -0,0 +1,42 @@
+from _typeshed import Incomplete
+from gl_computer_use.agent._takeover import TakeoverPolicy as TakeoverPolicy, handle_takeover as handle_takeover
+from gl_computer_use.agent.base import BaseAgent as BaseAgent
+from gl_computer_use.config import GLComputerUseConfig as GLComputerUseConfig
+from gl_computer_use.errors import AgentError as AgentError
+from gl_computer_use.observability.logging import get_logger as get_logger
+from gl_computer_use.observability.tracing import start_span as start_span
+from gl_computer_use.types import ActionDetail as ActionDetail, RunContext as RunContext, TaskEvent as TaskEvent, TaskResult as TaskResult
+
+logger: Incomplete
+
+class AgentSAgent(BaseAgent):
+    """BaseAgent implementation wrapping simular-ai/Agent-S.
+
+    Drives the external [screenshot → predict → execute] loop and translates
+    each iteration into typed TaskEvent objects. Supports full Phase-2
+    takeover semantics via the shared _takeover module.
+
+    Attributes:
+        _config: SDK configuration including agents_* tuning parameters.
+        _policy: Takeover policy tracker for the current run.
+    """
+    def __init__(self, config: GLComputerUseConfig) -> None:
+        """Initialise AgentSAgent, verifying the gui-agents import early.
+
+        Args:
+            config: SDK configuration with agents_* and model fields.
+
+        Raises:
+            ImportError: When gui-agents is not installed.
+        """
+    async def run(self, ctx: RunContext) -> None:
+        """Drive the Agent-S loop and emit events onto ctx.event_queue.
+
+        Emits TASK_STARTED, one STEP_COMPLETED per real action (plus SCREENSHOT
+        events for noop frames), optional TAKEOVER_STARTED / TAKEOVER_RESUMED
+        pairs, and a terminal event.
+
+        Args:
+            ctx: Per-task runtime bundle with sandbox, event queue, model
+                identity, and cancellation/pause controls.
+        """

gl_computer_use/agent/base.pyi

@@ -0,0 +1,31 @@
+from abc import ABC, abstractmethod
+from gl_computer_use.types import RunContext as RunContext
+
+class BaseAgent(ABC):
+    """Abstract base class for computer-use agent providers.
+
+    Concrete implementations wrap a specific agent framework (Agent-S, or a
+    custom registered agent) and drive the observe-plan-act loop, emitting
+    TaskEvent objects onto the queue in RunContext.
+
+    Attributes:
+        supports_trajectory_persistence: Whether the agent seeds
+            ``ctx._resume_history`` into its own conversation state on resume
+            and writes its running trajectory back to ``ctx._captured_history``
+            for the runner to persist on snapshot. False by default — a
+            snapshot/resume cycle still preserves the desktop, but the agent
+            restarts each task with no memory of the prior conversation.
+            Override to True only once both sides are actually wired up.
+    """
+    supports_trajectory_persistence: bool
+    @abstractmethod
+    async def run(self, ctx: RunContext) -> None:
+        """Drive the agent loop and emit step events onto ctx.event_queue.
+
+        Implementations must emit a terminal event (TASK_COMPLETED,
+        TASK_FAILED, or TASK_CANCELLED) as the final item before returning.
+
+        Args:
+            ctx: Per-task runtime bundle including sandbox, event queue,
+                model identity, and cancellation/pause controls.
+        """

gl_computer_use/agent/openai_agent.pyi

@@ -0,0 +1,34 @@
+from _typeshed import Incomplete
+from gl_computer_use.agent._takeover import TakeoverPolicy as TakeoverPolicy, handle_takeover as handle_takeover
+from gl_computer_use.agent.base import BaseAgent as BaseAgent
+from gl_computer_use.config import GLComputerUseConfig as GLComputerUseConfig
+from gl_computer_use.errors import AgentError as AgentError
+from gl_computer_use.observability.logging import get_logger as get_logger
+from gl_computer_use.observability.tracing import start_span as start_span
+from gl_computer_use.types import ActionDetail as ActionDetail, RunContext as RunContext, TaskEvent as TaskEvent, TaskResult as TaskResult
+
+logger: Incomplete
+
+class OpenAIAgent(BaseAgent):
+    '''BaseAgent implementation wrapping OpenAI\'s Responses API "computer" tool.
+
+    Attributes:
+        _config: SDK configuration (openai_api_key, max_steps, stuck patterns).
+    '''
+    supports_trajectory_persistence: bool
+    def __init__(self, config: GLComputerUseConfig) -> None:
+        """Initialise OpenAIAgent, verifying the `openai` package is importable.
+
+        Args:
+            config: SDK configuration with openai_api_key and model fields.
+
+        Raises:
+            ImportError: When the `openai` package is not installed.
+        """
+    async def run(self, ctx: RunContext) -> None:
+        """Drive the OpenAI computer-use loop and emit events onto ctx.event_queue.
+
+        Args:
+            ctx: Per-task runtime bundle with sandbox, event queue, model
+                identity, and cancellation/pause controls.
+        """

gl_computer_use/agent/runner.pyi

@@ -0,0 +1,158 @@
+import asyncio
+from _typeshed import Incomplete
+from gl_computer_use.agent.base import BaseAgent as BaseAgent
+from gl_computer_use.artifact.base import BaseArtifact as BaseArtifact
+from gl_computer_use.config import GLComputerUseConfig as GLComputerUseConfig
+from gl_computer_use.errors import ConfigError as ConfigError, GLComputerUseError as GLComputerUseError, ResumeError as ResumeError, SnapshotError as SnapshotError
+from gl_computer_use.observability.logging import get_logger as get_logger
+from gl_computer_use.observability.metrics import inc_active_sandboxes as inc_active_sandboxes, inc_artifact_upload_failure as inc_artifact_upload_failure, inc_model_drift as inc_model_drift, inc_snapshot_failure as inc_snapshot_failure, inc_snapshot_gc as inc_snapshot_gc, record_artifact_upload as record_artifact_upload, record_provision_seconds as record_provision_seconds, record_resume_seconds as record_resume_seconds, record_snapshot_history_bytes as record_snapshot_history_bytes, record_snapshot_seconds as record_snapshot_seconds
+from gl_computer_use.observability.tracing import start_span as start_span
+from gl_computer_use.recording import PlaywrightRecorder as PlaywrightRecorder, ScreenshotStitcher as ScreenshotStitcher, is_playwright_available as is_playwright_available
+from gl_computer_use.registry import get_registry as get_registry
+from gl_computer_use.sandbox.base import BaseSandbox as BaseSandbox
+from gl_computer_use.types import AgentSession as AgentSession, ResumeToken as ResumeToken, RunContext as RunContext, SandboxDisposition as SandboxDisposition, TaskEvent as TaskEvent
+
+logger: Incomplete
+
+class AgentRunner:
+    """Orchestrates the agent loop, sandbox lifecycle, and artifact persistence.
+
+    One AgentRunner is created per Session. Callers interact via prepare(),
+    start_agent_task(), on_task_ending(), and cleanup().
+
+    Attributes:
+        _config: SDK configuration.
+        _artifact_store: Artifact backend for persisting screenshots and files.
+        _session_id: Parent session UUID (used for artifact paths).
+        _sandbox: Provisioned sandbox instance; set after prepare().
+        _agent: Agent provider instance; set after prepare().
+        _stream_url: VNC stream URL; set after prepare() if available.
+        _recorder: PlaywrightRecorder instance for session recording.
+        _screenshot_bytes: Accumulates raw PNG bytes for stitching fallback.
+        _screenshot_urls: Accumulates presigned URLs returned by artifact_store.
+        _recording_stopped: True once on_task_ending has finished recording.
+    """
+    def __init__(self, config: GLComputerUseConfig, artifact_store: BaseArtifact, session_id: str) -> None:
+        """Initialise the AgentRunner with config, artifact store, and session ID.
+
+        Args:
+            config: SDK configuration for this session.
+            artifact_store: Backend for persisting screenshots, files, and recordings.
+            session_id: Parent session UUID used for artifact paths.
+        """
+    def set_disposition(self, disposition: SandboxDisposition | str) -> None:
+        """Set the teardown disposition for this runner instance."""
+    async def prepare(self, resume_from: ResumeToken | None = None) -> str | None:
+        """Provision (or restore) the sandbox, build the agent, start recording.
+
+        When ``resume_from`` is provided the sandbox is restored from the token's
+        snapshot instead of provisioned fresh, and the saved agent trajectory is
+        loaded so the next run continues the conversation.
+
+        Args:
+            resume_from: A ResumeToken to restore from, or ``None`` for a fresh
+                sandbox.
+
+        Returns:
+            The VNC stream URL if the sandbox exposes one, otherwise None.
+
+        Raises:
+            SandboxProvisionError: When the sandbox cannot be allocated.
+            ResumeError: When restoring from a snapshot fails.
+        """
+    async def cleanup(self) -> None:
+        """Destroy the sandbox and ensure recording is stopped (crash/reset path).
+
+        This is the disposition-agnostic teardown (always DESTROY). Resumable
+        teardown goes through :meth:`finalize`.
+        """
+    async def finalize(self, disposition: SandboxDisposition) -> ResumeToken | None:
+        """Disposition-aware teardown: optionally snapshot, then release the box.
+
+        On ``SNAPSHOT`` (and when the live sandbox has not already been
+        snapshotted by :meth:`on_task_ending`), this captures a durable snapshot
+        plus the agent trajectory into a :class:`ResumeToken`, GCs the
+        predecessor, then destroys the live handle (the snapshot has already
+        freed the compute). On ``DESTROY`` it just releases the box.
+
+        Args:
+            disposition: How to dispose of the sandbox.
+
+        Returns:
+            The successor :class:`ResumeToken` when one was produced, else None.
+
+        Raises:
+            SnapshotError: Under ``strict_snapshot=True``, when the capture
+                fails. The sandbox is still destroyed before this propagates —
+                see the ``finally`` below — so a caller (e.g.
+                ``Session.__aexit__``, which calls this directly with no
+                cleanup fallback of its own on a clean exit) never leaks it.
+        """
+    def create_agent_session(self, task_id: str, prompt: str) -> AgentSession:
+        """Build a lean AgentSession identity record for a task.
+
+        The returned object contains only the immutable, serialisable fields
+        that identify the task. Runtime handles live in RunContext, which is
+        created separately via create_run_context().
+
+        Args:
+            task_id: Unique identifier for the task.
+            prompt: The user-supplied task description.
+
+        Returns:
+            An AgentSession with session_id, task_id, prompt, and model.
+        """
+    def create_run_context(self, agent_session: AgentSession, event_queue: asyncio.Queue[TaskEvent], retrieve_files: list[str] | None = None) -> RunContext:
+        """Build the ephemeral RunContext for one task execution.
+
+        Creates the asyncio control events and binds the live sandbox handle.
+        Must be called after prepare() so that self._sandbox is available.
+
+        Args:
+            agent_session: Identity record returned by create_agent_session().
+            event_queue: Queue that agent events will be placed onto.
+            retrieve_files: Sandbox paths to fetch after task completion.
+
+        Returns:
+            A RunContext ready to be passed to BaseAgent.run().
+
+        Raises:
+            GLComputerUseError: When prepare() has not been called yet.
+        """
+    def start_agent_task(self, run_ctx: RunContext) -> asyncio.Task[None]:
+        """Start the agent loop as a background asyncio.Task.
+
+        Used by both the Layer 1 streaming path and the Layer 2 session path.
+        The caller drains run_ctx.event_queue independently.
+
+        Args:
+            run_ctx: Pre-built RunContext for this task run.
+
+        Returns:
+            The asyncio.Task driving the agent loop.
+
+        Raises:
+            GLComputerUseError: When prepare() has not been called yet.
+        """
+    async def on_task_ending(self, event: TaskEvent, retrieve_files: list[str] | None = None) -> TaskEvent:
+        """Stop recording, upload artifacts, and patch the terminal TaskResult.
+
+        Called by StreamClient before the terminal event is yielded to the
+        caller. This ensures recording_url/status and screenshot_urls are
+        populated in the TaskResult the caller receives.
+
+        Args:
+            event: The terminal TaskEvent (TASK_COMPLETED/FAILED/CANCELLED).
+            retrieve_files: Sandbox paths to fetch from the sandbox. Passed
+                explicitly so no dynamic attribute is needed on TaskEvent.
+
+        Returns:
+            The (potentially mutated) TaskEvent with artifact info attached.
+        """
+    @staticmethod
+    def new_task_id() -> str:
+        """Generate a new unique task ID.
+
+        Returns:
+            A UUID4 string.
+        """

gl_computer_use/artifact/base.pyi

@@ -0,0 +1,83 @@
+from abc import ABC, abstractmethod
+
+class BaseArtifact(ABC):
+    """Abstract base class for artifact storage backends.
+
+    Concrete implementations write screenshots, files, and recordings to a
+    backing store (local disk in Phase 1; S3-compatible object store in Phase 2).
+    """
+    supports_history: bool
+    @abstractmethod
+    async def save_screenshot(self, session_id: str, seq: int, data: bytes) -> str:
+        """Persist a screenshot and return its storage URI.
+
+        Args:
+            session_id: The session that produced this screenshot.
+            seq: Zero-based step sequence number used for ordering.
+            data: Raw PNG bytes.
+
+        Returns:
+            A URI string pointing to the stored artifact.
+        """
+    @abstractmethod
+    async def save_file(self, session_id: str, path: str, data: bytes) -> str:
+        """Persist an arbitrary file and return its storage URI.
+
+        Args:
+            session_id: The session that produced this file.
+            path: Original file path on the sandbox (used to derive the filename).
+            data: Raw file bytes.
+
+        Returns:
+            A URI string pointing to the stored artifact.
+        """
+    @abstractmethod
+    async def save_recording(self, session_id: str, data: bytes, ext: str) -> str:
+        '''Persist a screen recording and return its storage URI.
+
+        Args:
+            session_id: The session that produced this recording.
+            data: Raw recording bytes.
+            ext: File extension without leading dot (e.g. ``"mp4"``).
+
+        Returns:
+            A URI string pointing to the stored artifact.
+        '''
+    async def save_history(self, session_id: str, data: bytes) -> str:
+        """Persist the agent trajectory JSON and return a stable URI.
+
+        Args:
+            session_id: The session that produced this trajectory.
+            data: UTF-8 JSON bytes of the conversation trajectory.
+
+        Returns:
+            A stable URI that :meth:`load_history` and :meth:`delete_history`
+            can resolve (e.g. ``file://...`` or ``s3://bucket/key`` — never a
+            presigned, expiring URL).
+
+        Raises:
+            NotImplementedError: When the store does not support history.
+        """
+    async def load_history(self, uri: str) -> bytes:
+        """Load a previously saved trajectory by its stable URI.
+
+        Args:
+            uri: A URI returned by :meth:`save_history`.
+
+        Returns:
+            The raw JSON bytes of the trajectory.
+
+        Raises:
+            NotImplementedError: When the store does not support history.
+        """
+    async def delete_history(self, uri: str) -> None:
+        """Delete a saved trajectory by its stable URI (for rolling GC).
+
+        A missing/already-deleted trajectory should be treated as success.
+
+        Args:
+            uri: A URI returned by :meth:`save_history`.
+
+        Raises:
+            NotImplementedError: When the store does not support history.
+        """

gl_computer_use/artifact/local.pyi

@@ -0,0 +1,79 @@
+from gl_computer_use.artifact.base import BaseArtifact as BaseArtifact
+from gl_computer_use.config import GLComputerUseConfig as GLComputerUseConfig
+
+class LocalArtifact(BaseArtifact):
+    """Artifact store that persists data to the local filesystem.
+
+    All write operations use aiofiles for true async I/O without occupying
+    thread-pool slots.
+
+    Attributes:
+        _root: Path to the configured artifact root directory.
+    """
+    supports_history: bool
+    def __init__(self, config: GLComputerUseConfig) -> None:
+        """Initialise the LocalArtifact store.
+
+        Args:
+            config: SDK configuration; uses config.local_artifact_dir as the root.
+        """
+    async def save_screenshot(self, session_id: str, seq: int, data: bytes) -> str:
+        """Write a PNG screenshot to disk and return its file:// URI.
+
+        Args:
+            session_id: The session that produced this screenshot.
+            seq: Zero-based step sequence number.
+            data: Raw PNG bytes.
+
+        Returns:
+            A ``file://`` URI for the stored screenshot.
+        """
+    async def save_file(self, session_id: str, path: str, data: bytes) -> str:
+        """Write a sandbox file to disk and return its file:// URI.
+
+        Args:
+            session_id: The session that produced this file.
+            path: Original file path on the sandbox; preserved as sanitised path
+                segments (leading ``/`` and ``..``/``.`` stripped) so files with
+                the same basename from different directories do not collide.
+            data: Raw file bytes.
+
+        Returns:
+            A ``file://`` URI for the stored file.
+        """
+    async def save_recording(self, session_id: str, data: bytes, ext: str) -> str:
+        '''Write a screen recording to disk and return its file:// URI.
+
+        Args:
+            session_id: The session that produced this recording.
+            data: Raw recording bytes.
+            ext: File extension without leading dot (e.g. ``"mp4"``).
+
+        Returns:
+            A ``file://`` URI for the stored recording.
+        '''
+    async def save_history(self, session_id: str, data: bytes) -> str:
+        """Write the agent trajectory JSON to disk and return its file:// URI.
+
+        Args:
+            session_id: The session that produced this trajectory.
+            data: UTF-8 JSON bytes of the conversation trajectory.
+
+        Returns:
+            A ``file://`` URI for the stored trajectory.
+        """
+    async def load_history(self, uri: str) -> bytes:
+        """Read a trajectory JSON file given its file:// URI.
+
+        Args:
+            uri: A ``file://`` URI from :meth:`save_history`.
+
+        Returns:
+            The raw JSON bytes.
+        """
+    async def delete_history(self, uri: str) -> None:
+        """Delete a trajectory file; a missing file is treated as success.
+
+        Args:
+            uri: A ``file://`` URI from :meth:`save_history`.
+        """

gl_computer_use/artifact/minio.pyi

@@ -0,0 +1,123 @@
+from _typeshed import Incomplete
+from gl_computer_use._urls import split_scheme as split_scheme
+from gl_computer_use.artifact.base import BaseArtifact as BaseArtifact
+from gl_computer_use.config import GLComputerUseConfig as GLComputerUseConfig
+from gl_computer_use.errors import ArtifactStoreError as ArtifactStoreError
+from gl_computer_use.observability.logging import get_logger as get_logger
+from gl_computer_use.observability.retries import retry_artifact as retry_artifact
+from gl_computer_use.observability.tracing import start_span as start_span
+
+logger: Incomplete
+
+class MinIOArtifact(BaseArtifact):
+    """BaseArtifact backed by a MinIO (S3-compatible) object store.
+
+    All SDK calls use aiobotocore for true async I/O — no thread pool involved.
+    Each save method returns a presigned URL valid for
+    ``config.presigned_url_expiry_seconds``.
+
+    Attributes:
+        _endpoint_url: MinIO server endpoint URL (with scheme), or ``None`` for
+            the AWS S3 global endpoint so botocore resolves the regional endpoint
+            from ``_region``.
+        _access_key: MinIO access key.
+        _secret_key: MinIO secret key.
+        _bucket: Target bucket name.
+        _region: AWS region of the bucket (None for region-agnostic MinIO).
+        _prefix: Optional key prefix within the bucket (empty = bucket root).
+        _expiry: Presigned URL TTL in seconds.
+        _session: aiobotocore session for creating async S3 clients.
+        _bucket_ensured: Flag so bucket creation only runs once.
+        _bucket_lock: asyncio.Lock guarding the once-only bucket init.
+    """
+    supports_history: bool
+    def __init__(self, config: GLComputerUseConfig) -> None:
+        """Initialise MinIOArtifact from the SDK configuration.
+
+        Args:
+            config: SDK configuration with object_store_* fields populated.
+
+        Raises:
+            ImportError: When the aiobotocore package is not installed.
+            ArtifactStoreError: When the endpoint is absent.
+        """
+    async def save_screenshot(self, session_id: str, seq: int, data: bytes) -> str:
+        """Upload a screenshot PNG and return a presigned URL.
+
+        Args:
+            session_id: Parent session UUID (used for object key prefix).
+            seq: Zero-based step sequence number.
+            data: Raw PNG bytes.
+
+        Returns:
+            Presigned GET URL valid for ``presigned_url_expiry_seconds``.
+
+        Raises:
+            ArtifactStoreError: On upload failure.
+        """
+    async def save_file(self, session_id: str, path: str, data: bytes) -> str:
+        """Upload a retrieved sandbox file and return a presigned URL.
+
+        Args:
+            session_id: Parent session UUID.
+            path: Original sandbox path; preserved as sanitised key segments
+                (leading ``/`` and ``..``/``.`` segments stripped) so files with
+                the same basename from different directories do not collide.
+            data: Raw file bytes.
+
+        Returns:
+            Presigned GET URL valid for ``presigned_url_expiry_seconds``.
+
+        Raises:
+            ArtifactStoreError: On upload failure.
+        """
+    async def save_recording(self, session_id: str, data: bytes, ext: str) -> str:
+        '''Upload a session recording and return a presigned URL.
+
+        Args:
+            session_id: Parent session UUID.
+            data: Raw recording bytes (WebM or GIF).
+            ext: File extension without leading dot (e.g. ``"webm"`` or ``"gif"``).
+
+        Returns:
+            Presigned GET URL valid for ``presigned_url_expiry_seconds``.
+
+        Raises:
+            ArtifactStoreError: On upload failure.
+        '''
+    async def save_history(self, session_id: str, data: bytes) -> str:
+        """Upload the agent trajectory JSON and return a stable s3:// URI.
+
+        Unlike the screenshot/recording helpers, this returns a stable
+        ``s3://bucket/key`` reference (not a presigned, expiring URL) so the URI
+        can be stored in a long-lived :class:`ResumeToken` and later resolved by
+        :meth:`load_history` / :meth:`delete_history`.
+
+        Args:
+            session_id: The session that produced this trajectory.
+            data: UTF-8 JSON bytes of the conversation trajectory.
+
+        Returns:
+            A stable ``s3://bucket/key`` URI.
+
+        Raises:
+            ArtifactStoreError: On upload failure.
+        """
+    async def load_history(self, uri: str) -> bytes:
+        """Download a trajectory JSON given its s3:// URI.
+
+        Args:
+            uri: An ``s3://bucket/key`` URI from :meth:`save_history`.
+
+        Returns:
+            The raw JSON bytes.
+
+        Raises:
+            ArtifactStoreError: On download failure.
+        """
+    async def delete_history(self, uri: str) -> None:
+        """Delete a trajectory object; failures are logged, not raised.
+
+        Args:
+            uri: An ``s3://bucket/key`` URI from :meth:`save_history`.
+        """