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,151 @@
1
+ """Ordered structured events for terminal, GUI, and plugin observers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ from collections.abc import Awaitable, Callable, Iterable
7
+ from contextlib import suppress
8
+ from dataclasses import dataclass, field
9
+ from datetime import datetime, timezone
10
+ from typing import Any, Literal, TypeAlias
11
+
12
+ RuntimeEventKind = Literal[
13
+ "turn_started",
14
+ "model_started",
15
+ "text_delta",
16
+ "reasoning_delta",
17
+ "answer_to_thinking",
18
+ "model_finished",
19
+ "route_changed",
20
+ "usage",
21
+ "compacted",
22
+ "tool_started",
23
+ "tool_preview",
24
+ "tool_finished",
25
+ "turn_succeeded",
26
+ "turn_blocked",
27
+ "turn_interrupted",
28
+ "turn_failed",
29
+ ]
30
+
31
+
32
+ def _timestamp() -> str:
33
+ return datetime.now(timezone.utc).isoformat()
34
+
35
+
36
+ @dataclass(frozen=True)
37
+ class RuntimeEvent:
38
+ """One serializable event in a single run's ordered stream."""
39
+
40
+ kind: RuntimeEventKind
41
+ seq: int
42
+ run_id: str
43
+ timestamp: str = field(default_factory=_timestamp)
44
+ turn: int | None = None
45
+ payload: dict[str, Any] = field(default_factory=dict)
46
+
47
+ def to_dict(self) -> dict[str, Any]:
48
+ return {
49
+ "kind": self.kind,
50
+ "seq": self.seq,
51
+ "run_id": self.run_id,
52
+ "timestamp": self.timestamp,
53
+ "turn": self.turn,
54
+ "payload": dict(self.payload),
55
+ }
56
+
57
+
58
+ EventListener: TypeAlias = Callable[[RuntimeEvent], Any | Awaitable[Any]]
59
+
60
+
61
+ @dataclass(frozen=True)
62
+ class ListenerError:
63
+ """An isolated observer failure, available for logging and diagnostics."""
64
+
65
+ error: Exception
66
+ event: RuntimeEvent
67
+ listener: EventListener
68
+
69
+
70
+ @dataclass(frozen=True)
71
+ class _Subscription:
72
+ listener: EventListener
73
+ kinds: frozenset[str] | None = None
74
+
75
+
76
+ ErrorListener = Callable[[ListenerError], Any]
77
+
78
+
79
+ class EventBus:
80
+ """Process-local subscriptions; each run gets an independent sequence/ID.
81
+
82
+ Observer failures are isolated from the agent loop and recorded in
83
+ ``errors``. An optional error listener can forward them to a host logger.
84
+ Event delivery is ordered and backpressured: an async GUI subscriber must
85
+ finish handling one event before the next is delivered to that subscriber.
86
+ """
87
+
88
+ def __init__(self, *, on_error: ErrorListener | None = None) -> None:
89
+ self._subscriptions: list[_Subscription] = []
90
+ self._on_error = on_error
91
+ self.errors: list[ListenerError] = []
92
+
93
+ def subscribe(
94
+ self, listener: EventListener, *, kinds: Iterable[RuntimeEventKind] | None = None
95
+ ) -> Callable[[], None]:
96
+ """Subscribe and return an idempotent unsubscribe callback."""
97
+
98
+ subscription = _Subscription(listener, frozenset(kinds) if kinds is not None else None)
99
+ self._subscriptions.append(subscription)
100
+
101
+ def unsubscribe() -> None:
102
+ with suppress(ValueError):
103
+ self._subscriptions.remove(subscription)
104
+
105
+ return unsubscribe
106
+
107
+ def for_run(self, run_id: str, *, listeners: Iterable[EventListener] = ()) -> EventEmitter:
108
+ local = [_Subscription(listener) for listener in listeners]
109
+ return EventEmitter(self, run_id, local)
110
+
111
+ async def _dispatch(self, event: RuntimeEvent, local: list[_Subscription]) -> None:
112
+ for subscription in (*self._subscriptions, *local):
113
+ if subscription.kinds is not None and event.kind not in subscription.kinds:
114
+ continue
115
+ try:
116
+ result = subscription.listener(event)
117
+ if asyncio.iscoroutine(result) or isinstance(result, Awaitable):
118
+ await result
119
+ except Exception as error: # observers must not break a model/tool round
120
+ failure = ListenerError(error, event, subscription.listener)
121
+ self.errors.append(failure)
122
+ if self._on_error is not None:
123
+ # Diagnostics are observers too; never recursively fail a run.
124
+ with suppress(Exception):
125
+ self._on_error(failure)
126
+
127
+
128
+ class EventEmitter:
129
+ """The write side of one run's event stream, passed to backends/tools."""
130
+
131
+ def __init__(
132
+ self, bus: EventBus, run_id: str, local: list[_Subscription] | None = None
133
+ ) -> None:
134
+ self._bus = bus
135
+ self.run_id = run_id
136
+ self._local = local or []
137
+ self._seq = 0
138
+
139
+ async def emit(
140
+ self, kind: RuntimeEventKind, *, turn: int | None = None, **payload: Any
141
+ ) -> RuntimeEvent:
142
+ self._seq += 1
143
+ event = RuntimeEvent(
144
+ kind=kind,
145
+ seq=self._seq,
146
+ run_id=self.run_id,
147
+ turn=turn,
148
+ payload=payload,
149
+ )
150
+ await self._bus._dispatch(event, self._local)
151
+ return event
@@ -0,0 +1,243 @@
1
+ """Provider-neutral filesystem tool implementations."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import difflib
6
+ import os
7
+ import tempfile
8
+ from collections.abc import Callable
9
+ from contextlib import suppress
10
+ from pathlib import Path
11
+ from typing import Any, Protocol
12
+
13
+ from .types import ToolResult
14
+
15
+ MAX_READ_CHARS = 50_000
16
+ DEFAULT_READ_LINES = 200
17
+ IMAGE_SUFFIX_MIME = {
18
+ ".png": "image/png",
19
+ ".jpg": "image/jpeg",
20
+ ".jpeg": "image/jpeg",
21
+ ".webp": "image/webp",
22
+ ".gif": "image/gif",
23
+ ".bmp": "image/bmp",
24
+ }
25
+
26
+
27
+ class ImageReader(Protocol):
28
+ """Host-provided image processing, keeping optional Pillow out of the core."""
29
+
30
+ def read(self, path: Path, mime_type: str | None) -> ToolResult: ...
31
+
32
+
33
+ class VisionSupport(Protocol):
34
+ """Host policy for whether the active model can consume an attachment."""
35
+
36
+ def __call__(self, model: str | None) -> bool: ...
37
+
38
+
39
+ def resolve_path(cwd: Path, path: str) -> Path:
40
+ p = Path(path.removeprefix("@").replace("\\ ", " ")).expanduser()
41
+ return p if p.is_absolute() else cwd / p
42
+
43
+
44
+ def detect_image_mime(path: Path) -> str | None:
45
+ """Suffix first, then magic bytes, so a suffix-less screenshot still works."""
46
+
47
+ mime = IMAGE_SUFFIX_MIME.get(path.suffix.lower())
48
+ if mime:
49
+ return mime
50
+ try:
51
+ with path.open("rb") as fh:
52
+ head = fh.read(16)
53
+ except OSError:
54
+ return None
55
+ if head.startswith(b"\x89PNG\r\n\x1a\n"):
56
+ return "image/png"
57
+ if head.startswith(b"\xff\xd8\xff"):
58
+ return "image/jpeg"
59
+ if head.startswith((b"GIF87a", b"GIF89a")):
60
+ return "image/gif"
61
+ if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
62
+ return "image/webp"
63
+ if head.startswith(b"BM"):
64
+ return "image/bmp"
65
+ return None
66
+
67
+
68
+ def write_atomic(fp: Path, text: str) -> None:
69
+ """Temp file + os.replace: an interrupted write can never truncate the file."""
70
+
71
+ target = fp.resolve() if fp.is_symlink() else fp # keep symlinks pointing where they did
72
+ target.parent.mkdir(parents=True, exist_ok=True)
73
+ fd, tmp_name = tempfile.mkstemp(dir=target.parent, prefix=f".{target.name}.", suffix=".tmp")
74
+ tmp = Path(tmp_name)
75
+ try:
76
+ with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as f:
77
+ f.write(text)
78
+ f.flush()
79
+ os.fsync(f.fileno())
80
+ with suppress(OSError):
81
+ os.chmod(tmp, target.stat().st_mode & 0o7777)
82
+ os.replace(tmp, target)
83
+ finally:
84
+ tmp.unlink(missing_ok=True)
85
+
86
+
87
+ def count_lines(fp: Path) -> int:
88
+ """Total line count at C speed (bytes.count) so a 100 MB log stays fast."""
89
+
90
+ total, tail = 0, b"\n"
91
+ with fp.open("rb") as fh:
92
+ for chunk in iter(lambda: fh.read(1 << 20), b""):
93
+ total += chunk.count(b"\n")
94
+ tail = chunk[-1:]
95
+ return total if tail == b"\n" or total == 0 else total + 1
96
+
97
+
98
+ def _truncate_text(s: str, limit: int, *, tag: str = "truncated") -> str:
99
+ return s if len(s) <= limit else s[:limit] + f"\n...[{tag} {len(s) - limit} chars]"
100
+
101
+
102
+ def read_file(
103
+ cwd: Path | None,
104
+ path: str,
105
+ offset: int | None = None,
106
+ limit: int | None = None,
107
+ *,
108
+ model: str | None = None,
109
+ image_reader: ImageReader | None = None,
110
+ supports_vision: VisionSupport | None = None,
111
+ ) -> str | ToolResult:
112
+ if cwd is None:
113
+ return "error: no workspace is configured"
114
+ fp = resolve_path(cwd, path)
115
+ if not fp.is_file():
116
+ return f"error: not a file: {fp}"
117
+ mime = detect_image_mime(fp)
118
+ if mime:
119
+ if supports_vision is not None and not supports_vision(model):
120
+ return (
121
+ f"Read image file [{mime}]\n"
122
+ "[Current model does not support images. The image is omitted from this request.]"
123
+ )
124
+ if image_reader is None:
125
+ return f"error: image reader is not available for {fp}"
126
+ return image_reader.read(fp, mime)
127
+ want = limit if limit is not None and limit > 0 else DEFAULT_READ_LINES
128
+ start = max(0, (offset or 1) - 1) if offset is not None else 0
129
+ total = count_lines(fp)
130
+ window: list[str] = []
131
+ kept = end = 0
132
+ try:
133
+ # Only the wanted window is decoded and kept, and no single line can be
134
+ # unbounded: a 100 MB log costs a few hundred KB instead of 300 MB.
135
+ with fp.open(encoding="utf-8") as fh:
136
+ lineno = 0
137
+ while line := fh.readline(MAX_READ_CHARS + 1):
138
+ lineno += 1
139
+ if lineno > start + want or kept >= MAX_READ_CHARS:
140
+ break
141
+ if lineno <= start:
142
+ continue
143
+ text = line.rstrip("\r\n")
144
+ window.append(text)
145
+ kept += len(text) + 1
146
+ end = lineno
147
+ except UnicodeDecodeError:
148
+ return f"error: binary or non-utf8: {fp}"
149
+ end = end or min(start, total)
150
+ body = "\n".join(f"{i + start + 1}|{line}" for i, line in enumerate(window)) or "(empty)"
151
+ body = _truncate_text(body, MAX_READ_CHARS)
152
+ if start > 0 or end < total:
153
+ hint = f"...[lines {start + 1}-{end} of {total}"
154
+ if end < total:
155
+ hint += f"; continue with offset={end + 1}"
156
+ body = f"{body}\n{hint}]"
157
+ return body
158
+
159
+
160
+ def _write_stats(fp: Path, before: str, after: str, *, kind: str = "write") -> str:
161
+ a, b = before.splitlines(), after.splitlines()
162
+ add = delete = 0
163
+ for tag, i1, i2, j1, j2 in difflib.SequenceMatcher(a=a, b=b).get_opcodes():
164
+ if tag == "insert":
165
+ add += j2 - j1
166
+ elif tag == "delete":
167
+ delete += i2 - i1
168
+ elif tag == "replace":
169
+ delete += i2 - i1
170
+ add += j2 - j1
171
+ return f"{kind} {fp} +{add} -{delete}"
172
+
173
+
174
+ def write_file(
175
+ cwd: Path | None,
176
+ path: str,
177
+ content: str,
178
+ on_preview: Callable[[str], None] | None = None,
179
+ ) -> str:
180
+ if cwd is None:
181
+ return "error: no workspace is configured"
182
+ fp = resolve_path(cwd, path)
183
+ try:
184
+ before = fp.read_text(encoding="utf-8") if fp.exists() else ""
185
+ except UnicodeDecodeError:
186
+ return f"error: binary or non-utf8: {fp}"
187
+ after = content
188
+ if before == after and fp.is_file():
189
+ return f"no changes: {fp}"
190
+ if on_preview:
191
+ on_preview(_write_stats(fp, before, after, kind="write"))
192
+ write_atomic(fp, after)
193
+ return f"wrote {len(after.encode('utf-8'))} bytes to {fp}"
194
+
195
+
196
+ def edit_file(
197
+ cwd: Path | None,
198
+ path: str,
199
+ edits: list[dict[str, Any]],
200
+ on_preview: Callable[[str], None] | None = None,
201
+ ) -> str:
202
+ if cwd is None:
203
+ return "error: no workspace is configured"
204
+ fp = resolve_path(cwd, path)
205
+ if not fp.is_file():
206
+ return f"error: not a file: {fp}"
207
+ try:
208
+ before = fp.read_text(encoding="utf-8")
209
+ except UnicodeDecodeError:
210
+ return f"error: binary or non-utf8: {fp}"
211
+ if not isinstance(edits, list) or not edits:
212
+ return "error: edits must be a non-empty array"
213
+ spans: list[tuple[int, int, str, int]] = []
214
+ for i, ed in enumerate(edits):
215
+ if not isinstance(ed, dict):
216
+ return f"error: edits[{i}] must be an object"
217
+ old, new = ed.get("old_string"), ed.get("new_string")
218
+ if not isinstance(old, str) or not old:
219
+ return f"error: edits[{i}].old_string must be a non-empty string"
220
+ if not isinstance(new, str):
221
+ return f"error: edits[{i}].new_string must be a string"
222
+ n = before.count(old)
223
+ if n != 1:
224
+ return f"error: edits[{i}].old_string occurs {n} times in {fp}; expected exactly 1"
225
+ start = before.index(old)
226
+ spans.append((start, start + len(old), new, i))
227
+ ordered = sorted(spans, key=lambda s: s[0])
228
+ for a, b in zip(ordered, ordered[1:], strict=False):
229
+ if a[1] > b[0]:
230
+ return (
231
+ f"error: edits[{a[3]}] and edits[{b[3]}] overlap; "
232
+ "merge nearby changes into one edit"
233
+ )
234
+ after = before
235
+ for start, end, new, _ in sorted(spans, key=lambda s: s[0], reverse=True):
236
+ after = after[:start] + new + after[end:]
237
+ if before == after:
238
+ return f"no changes: {fp}"
239
+ if on_preview:
240
+ on_preview(_write_stats(fp, before, after, kind="edit"))
241
+ write_atomic(fp, after)
242
+ n = len(edits)
243
+ return f"edited {n} span{'s' if n != 1 else ''} in {fp}"
@@ -0,0 +1,155 @@
1
+ """Generic chat-history estimation and compaction policies."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from .responses import IMAGES_KEY, RAW_ITEMS_KEY, discard_raw_output
8
+ from .types import TOOL_ATTACHMENTS_KEY, Recovery
9
+
10
+ COMPACT_THRESHOLD, KEEP_USER_TURNS, KEEP_TOOL_RESULTS = 0.75, 3, 4
11
+ TOOL_MAX_CHARS, ASSISTANT_MAX_CHARS = 2_000, 4_000
12
+ OVERFLOW_RETRIES = 2
13
+ IMAGE_TOKEN_ESTIMATE = 1000
14
+
15
+
16
+ def _truncate(s: str, limit: int, *, tag: str = "truncated") -> str:
17
+ return s if len(s) <= limit else s[:limit] + f"\n...[{tag} {len(s) - limit} chars]"
18
+
19
+
20
+ def should_compact(
21
+ prompt_tokens: int | None, context_limit: int | None, *, threshold: float = COMPACT_THRESHOLD
22
+ ) -> bool:
23
+ if prompt_tokens is None or context_limit is None or context_limit <= 0:
24
+ return False
25
+ return prompt_tokens >= int(context_limit * threshold)
26
+
27
+
28
+ def compact_messages(
29
+ messages: list[dict[str, Any]],
30
+ *,
31
+ keep_user_turns: int = KEEP_USER_TURNS,
32
+ keep_tool_results: int = KEEP_TOOL_RESULTS,
33
+ tool_max_chars: int = TOOL_MAX_CHARS,
34
+ assistant_max_chars: int = ASSISTANT_MAX_CHARS,
35
+ ) -> tuple[list[dict[str, Any]], int]:
36
+ if not messages:
37
+ return messages, 0
38
+ head, rest = ([], messages)
39
+ if messages[0].get("role") == "system":
40
+ head, rest = [messages[0]], messages[1:]
41
+ user_idxs = [i for i, m in enumerate(rest) if m.get("role") == "user"]
42
+ keep_from = user_idxs[-keep_user_turns] if len(user_idxs) >= keep_user_turns else 0
43
+ tool_idxs = [i for i, m in enumerate(rest) if m.get("role") == "tool"]
44
+ old_tool_before = keep_from or len(rest)
45
+ if keep_from == 0 and tool_idxs:
46
+ old_tool_before = (
47
+ len(rest)
48
+ if keep_tool_results <= 0
49
+ else tool_idxs[max(0, len(tool_idxs) - keep_tool_results)]
50
+ )
51
+ out, changed = list(head), 0
52
+ for i, m in enumerate(rest):
53
+ role, content = m.get("role"), m.get("content")
54
+ if role == "tool" and i < old_tool_before:
55
+ updated = m
56
+ image_blocks = m.get(IMAGES_KEY) or m.get(TOOL_ATTACHMENTS_KEY)
57
+ if image_blocks:
58
+ updated = {
59
+ **updated,
60
+ "content": (content if isinstance(content, str) else "")
61
+ + "\n[image omitted: compacted]",
62
+ }
63
+ updated.pop(IMAGES_KEY, None)
64
+ updated.pop(TOOL_ATTACHMENTS_KEY, None)
65
+ content = updated["content"]
66
+ if isinstance(content, str) and len(content) > tool_max_chars:
67
+ updated = {
68
+ **updated,
69
+ "content": _truncate(content, tool_max_chars, tag="compacted"),
70
+ }
71
+ if updated is not m:
72
+ changed += 1
73
+ out.append(updated)
74
+ elif (
75
+ role == "assistant"
76
+ and i < keep_from
77
+ and isinstance(content, str)
78
+ and len(content) > assistant_max_chars
79
+ and not m.get("tool_calls")
80
+ ):
81
+ out.append({**m, "content": _truncate(content, assistant_max_chars, tag="compacted")})
82
+ changed += 1
83
+ else:
84
+ out.append(m)
85
+ return out, changed
86
+
87
+
88
+ def without_orphan_tool_results(messages: list[dict[str, Any]]) -> None:
89
+ """Drop tool results whose assistant call is no longer in history."""
90
+
91
+ calls = {
92
+ call.get("id")
93
+ for message in messages
94
+ if message.get("role") == "assistant"
95
+ for call in message.get("tool_calls") or []
96
+ }
97
+ messages[:] = [
98
+ message
99
+ for message in messages
100
+ if message.get("role") != "tool" or message.get("tool_call_id") in calls
101
+ ]
102
+
103
+
104
+ def estimate_tokens(messages: list[dict[str, Any]]) -> int:
105
+ """Rough size for providers that never report usage: ~4 chars per token."""
106
+
107
+ chars = images = 0
108
+ for message in messages:
109
+ chars += len(str(message.get("content") or ""))
110
+ images += len(message.get(IMAGES_KEY) or [])
111
+ images += len(message.get(TOOL_ATTACHMENTS_KEY) or [])
112
+ for call in message.get("tool_calls") or []:
113
+ chars += len(str((call.get("function") or {}).get("arguments") or ""))
114
+ return chars // 4 + images * IMAGE_TOKEN_ESTIMATE + 1
115
+
116
+
117
+ class ResponsesHistoryPolicy:
118
+ """OpenAI-compatible Responses compaction and safe-retry policy."""
119
+
120
+ def estimate(self, messages: list[dict[str, Any]]) -> int:
121
+ return estimate_tokens(messages)
122
+
123
+ def should_compact(self, prompt_tokens: int | None, context_limit: int | None) -> bool:
124
+ return should_compact(prompt_tokens, context_limit)
125
+
126
+ def compact(
127
+ self, messages: list[dict[str, Any]], *, aggressive: bool = False
128
+ ) -> tuple[list[dict[str, Any]], int]:
129
+ if aggressive:
130
+ new_messages, changed = compact_messages(
131
+ messages, keep_user_turns=1, keep_tool_results=1
132
+ )
133
+ else:
134
+ new_messages, changed = compact_messages(messages)
135
+ if changed:
136
+ discard_raw_output(new_messages)
137
+ without_orphan_tool_results(new_messages)
138
+ return new_messages, changed
139
+
140
+ def recover(
141
+ self,
142
+ messages: list[dict[str, Any]],
143
+ error: Exception,
144
+ *,
145
+ attempt: int,
146
+ ) -> Recovery | None:
147
+ from .openai_backend import is_context_overflow, is_tool_history_error
148
+
149
+ if is_tool_history_error(error) and any(RAW_ITEMS_KEY in message for message in messages):
150
+ discard_raw_output(messages)
151
+ return Recovery(messages)
152
+ if attempt > OVERFLOW_RETRIES or not is_context_overflow(error):
153
+ return None
154
+ new_messages, changed = self.compact(messages, aggressive=True)
155
+ return Recovery(new_messages, changed) if changed else None