agent0-runtime 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,167 @@
1
+ """Image decoding, normalization, vision policy, and tool attachments."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import base64
6
+ import io
7
+ from pathlib import Path
8
+
9
+ from PIL import Image, ImageOps
10
+
11
+ from .capabilities import MODEL_CAPABILITIES
12
+ from .filesystem import ImageReader
13
+ from .types import Attachment, ToolResult
14
+
15
+ SUPPORTED_MIME = ("image/png", "image/jpeg", "image/webp", "image/gif")
16
+ MIME_SUFFIX = {
17
+ ".png": "image/png",
18
+ ".jpg": "image/jpeg",
19
+ ".jpeg": "image/jpeg",
20
+ ".webp": "image/webp",
21
+ ".gif": "image/gif",
22
+ ".bmp": "image/bmp",
23
+ }
24
+ MIME_EXTENSION = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp", "image/gif": "gif"}
25
+ MAX_IMAGE_DIMENSION = 2000
26
+ MAX_IMAGE_BYTES = int(4.5 * 1024 * 1024)
27
+ IMAGE_TOKEN_ESTIMATE = 1000
28
+
29
+ _TEXT_ONLY = (
30
+ "text-",
31
+ "embedding",
32
+ "embed",
33
+ "whisper",
34
+ "tts",
35
+ "rerank",
36
+ "bge-",
37
+ "e5-",
38
+ "moderation",
39
+ )
40
+
41
+
42
+ def supports_vision(model: str | None) -> bool:
43
+ """Check reviewed capabilities first, then exclude known text-only families."""
44
+
45
+ name = (model or "").lower()
46
+ if not name:
47
+ return True
48
+ bare = name.rsplit("/", 1)[-1]
49
+ for capability in MODEL_CAPABILITIES:
50
+ if capability.model.lower() == bare:
51
+ return capability.supports_vision
52
+ return not any(hint in name for hint in _TEXT_ONLY)
53
+
54
+
55
+ def base_mime(mime_type: str) -> str:
56
+ return (mime_type or "").split(";")[0].strip().lower()
57
+
58
+
59
+ def detect_mime(path: Path) -> str | None:
60
+ """Use the suffix first, then magic bytes for suffix-less screenshots."""
61
+
62
+ mime = MIME_SUFFIX.get(path.suffix.lower())
63
+ if mime:
64
+ return mime
65
+ try:
66
+ with path.open("rb") as fh:
67
+ head = fh.read(16)
68
+ except OSError:
69
+ return None
70
+ if head.startswith(b"\x89PNG\r\n\x1a\n"):
71
+ return "image/png"
72
+ if head.startswith(b"\xff\xd8\xff"):
73
+ return "image/jpeg"
74
+ if head.startswith((b"GIF87a", b"GIF89a")):
75
+ return "image/gif"
76
+ if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
77
+ return "image/webp"
78
+ if head.startswith(b"BM"):
79
+ return "image/bmp"
80
+ return None
81
+
82
+
83
+ def _encode(image: Image.Image, mime_type: str, quality: int = 85) -> bytes:
84
+ out = io.BytesIO()
85
+ if mime_type == "image/jpeg":
86
+ image.convert("RGB").save(out, format="JPEG", quality=quality, optimize=True)
87
+ else:
88
+ image.save(out, format="PNG", optimize=True)
89
+ return out.getvalue()
90
+
91
+
92
+ def process_image(
93
+ data: bytes,
94
+ mime_type: str,
95
+ *,
96
+ max_dimension: int = MAX_IMAGE_DIMENSION,
97
+ max_bytes: int = MAX_IMAGE_BYTES,
98
+ ) -> tuple[Attachment, list[str]] | None:
99
+ """Normalize an image to a supported format and fit inline size limits."""
100
+
101
+ mime = base_mime(mime_type)
102
+ hints: list[str] = []
103
+ try:
104
+ with Image.open(io.BytesIO(data)) as opened:
105
+ image = ImageOps.exif_transpose(opened)
106
+ width, height = image.width, image.height
107
+ if (
108
+ mime in SUPPORTED_MIME
109
+ and len(data) <= max_bytes
110
+ and max(width, height) <= max_dimension
111
+ ):
112
+ # Keep original bytes so an animated GIF stays animated.
113
+ return Attachment(base64.b64encode(data).decode(), mime), hints
114
+ target = mime if mime in SUPPORTED_MIME else "image/png"
115
+ if target != mime:
116
+ hints.append(f"[Image converted from {mime or 'unknown'} to {target}.]")
117
+ if max(width, height) > max_dimension:
118
+ scale = max_dimension / max(width, height)
119
+ image = image.resize(
120
+ (max(1, round(width * scale)), max(1, round(height * scale))),
121
+ Image.Resampling.LANCZOS,
122
+ )
123
+ hints.append(
124
+ f"[Image resized from {width}x{height} to {image.width}x{image.height}.]"
125
+ )
126
+ candidates = [(_encode(image, target), target)]
127
+ if target != "image/gif":
128
+ candidates.append((_encode(image, "image/jpeg"), "image/jpeg"))
129
+ payload, final_mime = min(candidates, key=lambda candidate: len(candidate[0]))
130
+ while len(payload) > max_bytes and max(image.width, image.height) > 256:
131
+ image = image.resize(
132
+ (max(1, image.width * 3 // 4), max(1, image.height * 3 // 4)),
133
+ Image.Resampling.LANCZOS,
134
+ )
135
+ payload = _encode(image, "image/jpeg", quality=70)
136
+ final_mime = "image/jpeg"
137
+ if len(payload) > max_bytes:
138
+ return None
139
+ if final_mime != target:
140
+ hints.append(f"[Image re-encoded as {final_mime} to fit the size limit.]")
141
+ return Attachment(base64.b64encode(payload).decode(), final_mime), hints
142
+ except (OSError, ValueError):
143
+ return None
144
+
145
+
146
+ class PillowImageReader(ImageReader):
147
+ """Default ImageReader backed by Pillow and provider-neutral attachments."""
148
+
149
+ def read(self, path: Path, mime_type: str | None) -> ToolResult:
150
+ mime = mime_type or detect_mime(path) or ""
151
+ try:
152
+ data = path.read_bytes()
153
+ except OSError as e:
154
+ return ToolResult(f"error: {type(e).__name__}: {e}")
155
+ if not data:
156
+ return ToolResult(f"error: empty file: {path}")
157
+ processed = process_image(data, mime)
158
+ if processed is None:
159
+ return ToolResult(
160
+ f"Read image file [{mime or 'unknown'}]\n"
161
+ "[Image omitted: could not be converted to a supported inline image format.]"
162
+ )
163
+ attachment, hints = processed
164
+ text = f"Read image file [{attachment.mime_type}]"
165
+ if hints:
166
+ text += "\n" + "\n".join(hints)
167
+ return ToolResult(text, attachments=(attachment,))
@@ -0,0 +1,194 @@
1
+ """Read-only session/turn lifecycle hooks and run outcome classification."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import hashlib
7
+ from collections.abc import Awaitable, Callable, Mapping
8
+ from contextlib import suppress
9
+ from dataclasses import dataclass, field
10
+ from datetime import datetime, timezone
11
+ from pathlib import Path
12
+ from typing import Any, Literal, TypeAlias
13
+
14
+ from .types import AgentInterrupted, RunResult, RunStatus, new_run_id
15
+
16
+ LifecycleKind = Literal[
17
+ "session_started",
18
+ "turn_started",
19
+ "turn_succeeded",
20
+ "turn_interrupted",
21
+ "turn_blocked",
22
+ "turn_failed",
23
+ "session_ended",
24
+ ]
25
+
26
+
27
+ def _timestamp() -> str:
28
+ return datetime.now(timezone.utc).isoformat()
29
+
30
+
31
+ def _workspace_key(cwd: Path) -> str:
32
+ return hashlib.sha256(str(cwd.resolve()).encode("utf-8")).hexdigest()[:16]
33
+
34
+
35
+ @dataclass(frozen=True)
36
+ class LifecycleContext:
37
+ """Minimal session identity for lifecycle observers."""
38
+
39
+ session_id: str
40
+ cwd: Path | None = None
41
+ model: str = ""
42
+ metadata: Mapping[str, Any] = field(default_factory=dict)
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class LifecycleEvent:
47
+ kind: LifecycleKind
48
+ seq: int
49
+ session_id: str
50
+ cwd: Path | None = None
51
+ model: str = ""
52
+ reason: str = ""
53
+ run_id: str = ""
54
+ workspace_id: str = ""
55
+ timestamp: str = field(default_factory=_timestamp)
56
+
57
+
58
+ LifecycleListener: TypeAlias = Callable[[LifecycleEvent], Any]
59
+
60
+
61
+ @dataclass(frozen=True)
62
+ class LifecycleListenerError:
63
+ error: Exception
64
+ event: LifecycleEvent
65
+ listener: LifecycleListener
66
+
67
+
68
+ LifecycleErrorListener = Callable[[LifecycleListenerError], Any]
69
+
70
+
71
+ class LifecycleHooks:
72
+ """Ordered synchronous observers with fault isolation and unsubscribe.
73
+
74
+ Observers should be non-blocking. Async application integrations belong on
75
+ ``EventBus``; lifecycle hooks intentionally retain a tiny synchronous API.
76
+ """
77
+
78
+ def __init__(self, *, on_error: LifecycleErrorListener | None = None) -> None:
79
+ self._listeners: list[LifecycleListener] = []
80
+ self._seq = 0
81
+ self._on_error = on_error
82
+ self.errors: list[LifecycleListenerError] = []
83
+
84
+ def subscribe(self, listener: LifecycleListener) -> Callable[[], None]:
85
+ self._listeners.append(listener)
86
+
87
+ def unsubscribe() -> None:
88
+ with suppress(ValueError):
89
+ self._listeners.remove(listener)
90
+
91
+ return unsubscribe
92
+
93
+ def emit(
94
+ self,
95
+ kind: LifecycleKind,
96
+ session: Any,
97
+ *,
98
+ reason: str = "",
99
+ run_id: str = "",
100
+ ) -> None:
101
+ self._seq += 1
102
+ if isinstance(session, LifecycleContext):
103
+ context = session
104
+ else:
105
+ raw_cwd = getattr(session, "cwd", None) or getattr(session, "workspace", None)
106
+ cwd = Path(raw_cwd).resolve() if raw_cwd is not None else None
107
+ metadata = getattr(session, "metadata", None)
108
+ session_id = (
109
+ getattr(session, "id", "")
110
+ or getattr(session, "session_id", "")
111
+ or (metadata.get("session_id", "") if isinstance(metadata, Mapping) else "")
112
+ )
113
+ context = LifecycleContext(
114
+ session_id=str(session_id or "session"),
115
+ cwd=cwd,
116
+ model=str(
117
+ getattr(session, "model_ref", "")
118
+ or getattr(session, "model", "")
119
+ or (metadata.get("model", "") if isinstance(metadata, Mapping) else "")
120
+ ),
121
+ metadata=metadata if isinstance(metadata, Mapping) else {},
122
+ )
123
+ workspace_id = _workspace_key(context.cwd) if context.cwd is not None else ""
124
+ event = LifecycleEvent(
125
+ kind=kind,
126
+ seq=self._seq,
127
+ session_id=context.session_id,
128
+ cwd=context.cwd,
129
+ model=context.model,
130
+ reason=reason,
131
+ run_id=run_id,
132
+ workspace_id=workspace_id,
133
+ )
134
+ for listener in tuple(self._listeners):
135
+ try:
136
+ listener(event)
137
+ except Exception as error:
138
+ failure = LifecycleListenerError(error, event, listener)
139
+ self.errors.append(failure)
140
+ if self._on_error is not None:
141
+ with suppress(Exception):
142
+ self._on_error(failure)
143
+
144
+
145
+ def emit_lifecycle(
146
+ session: Any,
147
+ kind: LifecycleKind,
148
+ *,
149
+ reason: str = "",
150
+ run_id: str = "",
151
+ ) -> None:
152
+ """Emit through a Session, tolerating Session-like embedder objects."""
153
+
154
+ hooks = getattr(session, "hooks", None)
155
+ if hooks is not None:
156
+ hooks.emit(kind, session, reason=reason, run_id=run_id)
157
+
158
+
159
+ async def run_with_lifecycle(
160
+ session: Any,
161
+ work: Awaitable[RunResult],
162
+ *,
163
+ run_id: str = "",
164
+ hooks: LifecycleHooks | None = None,
165
+ ) -> RunResult:
166
+ """Classify one typed runner and emit exactly one end event."""
167
+
168
+ run_id = run_id or new_run_id()
169
+ hooks = hooks or getattr(session, "hooks", None)
170
+ if hooks is not None:
171
+ hooks.emit("turn_started", session, run_id=run_id)
172
+ try:
173
+ outcome = await work
174
+ except (AgentInterrupted, asyncio.CancelledError, KeyboardInterrupt) as error:
175
+ if hooks is not None:
176
+ reason = error.reason if isinstance(error, AgentInterrupted) else "interrupted"
177
+ hooks.emit("turn_interrupted", session, reason=reason, run_id=run_id)
178
+ raise
179
+ except Exception as error:
180
+ if hooks is not None:
181
+ hooks.emit("turn_failed", session, reason=type(error).__name__, run_id=run_id)
182
+ raise
183
+ result = outcome
184
+ if hooks is not None:
185
+ if result.status is RunStatus.BLOCKED:
186
+ hooks.emit(
187
+ "turn_blocked",
188
+ session,
189
+ reason=result.stop_reason or "blocked",
190
+ run_id=run_id,
191
+ )
192
+ else:
193
+ hooks.emit("turn_succeeded", session, run_id=run_id)
194
+ return result