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,161 @@
1
+ """Route selection and failover over the runtime Responses backend."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from agent0_runtime.events import EventEmitter
8
+ from agent0_runtime.openai_backend import (
9
+ OpenAIResponsesBackend,
10
+ RetryableResponseError,
11
+ can_failover_response_error,
12
+ completion_kwargs,
13
+ emit_callback,
14
+ stream_response_with_retries,
15
+ )
16
+ from agent0_runtime.responses import ResponseTurn
17
+ from agent0_runtime.types import ModelTurn
18
+
19
+ from .images import supports_vision
20
+ from .routing import FailoverRoute, RouteTarget
21
+
22
+
23
+ async def stream_response_failover(
24
+ route: FailoverRoute,
25
+ *,
26
+ messages: list[dict[str, Any]],
27
+ on_delta,
28
+ on_thinking,
29
+ on_answer_to_thinking,
30
+ on_finish,
31
+ on_route,
32
+ tools=None,
33
+ supports_model_vision=supports_vision,
34
+ retry_sleeps=(0.5, 1.5, 3.0),
35
+ close_timeout=2.0,
36
+ ) -> tuple[ResponseTurn, RouteTarget]:
37
+ """Replay only silent failed requests; never duplicate partial output."""
38
+
39
+ while True:
40
+ target = route.current
41
+ try:
42
+ turn = await stream_response_with_retries(
43
+ target.client,
44
+ completion_kwargs(
45
+ target.model,
46
+ messages,
47
+ target.provider_id,
48
+ tools,
49
+ vision=supports_model_vision(target.model),
50
+ ),
51
+ on_delta=on_delta,
52
+ on_thinking=on_thinking,
53
+ on_answer_to_thinking=on_answer_to_thinking,
54
+ on_finish=on_finish,
55
+ retry_sleeps=retry_sleeps,
56
+ close_timeout=close_timeout,
57
+ )
58
+ except RetryableResponseError as error:
59
+ next_target = route.advance() if can_failover_response_error(error.cause) else None
60
+ if next_target is None:
61
+ raise error.cause from None
62
+ await emit_callback(on_route, next_target, target, error.cause)
63
+ else:
64
+ return turn, target
65
+
66
+
67
+ class RoutedResponsesBackend(OpenAIResponsesBackend):
68
+ """Optional host-selected routing over a single-endpoint backend."""
69
+
70
+ def __init__(
71
+ self,
72
+ client,
73
+ model: str,
74
+ *,
75
+ route: FailoverRoute,
76
+ provider_id: str | None = None,
77
+ context_limit: int | None = None,
78
+ on_route=None,
79
+ retry_sleeps=(0.5, 1.5, 3.0),
80
+ stream_close_timeout=2.0,
81
+ ) -> None:
82
+ super().__init__(
83
+ client,
84
+ model,
85
+ supports_vision=supports_vision,
86
+ retry_sleeps=retry_sleeps,
87
+ stream_close_timeout=stream_close_timeout,
88
+ )
89
+ self.route = route
90
+ self._provider_id = provider_id
91
+ self._context_limit = context_limit
92
+ self.on_route = on_route
93
+
94
+ @property
95
+ def model(self) -> str:
96
+ return self.route.current.model
97
+
98
+ @property
99
+ def provider_id(self) -> str | None:
100
+ return self.route.current.provider_id
101
+
102
+ @property
103
+ def context_limit(self) -> int | None:
104
+ return self.route.current.context_limit
105
+
106
+ async def _route_changed(
107
+ self,
108
+ events: EventEmitter,
109
+ target: RouteTarget,
110
+ previous: RouteTarget | None,
111
+ error: BaseException | None,
112
+ ) -> None:
113
+ await events.emit(
114
+ "route_changed",
115
+ target=target.ref,
116
+ previous=previous.ref if previous is not None else None,
117
+ error=str(error) if error is not None else None,
118
+ error_type=type(error).__name__ if error is not None else None,
119
+ )
120
+ await emit_callback(self.on_route, target, previous, error)
121
+
122
+ async def prepare(self, task: str, messages, estimated_tokens: int, events) -> None:
123
+ await self.route.start(task, messages, estimated_tokens)
124
+ await self._route_changed(events, self.route.current, None, None)
125
+
126
+ async def complete(self, request, events: EventEmitter) -> ModelTurn:
127
+ if request.cancellation is not None:
128
+ request.cancellation.throw_if_cancelled(run_id=request.run_id)
129
+
130
+ async def on_delta(text) -> None:
131
+ await events.emit("text_delta", turn=request.turn, text=text)
132
+
133
+ async def on_thinking(text) -> None:
134
+ await events.emit("reasoning_delta", turn=request.turn, text=text)
135
+
136
+ async def on_answer_to_thinking() -> None:
137
+ await events.emit("answer_to_thinking", turn=request.turn)
138
+
139
+ async def on_finish(reason) -> None:
140
+ await events.emit("model_finished", turn=request.turn, finish_reason=reason)
141
+
142
+ async def changed(current, previous, error) -> None:
143
+ await self._route_changed(events, current, previous, error)
144
+
145
+ turn, target = await stream_response_failover(
146
+ self.route,
147
+ messages=request.messages,
148
+ on_delta=on_delta,
149
+ on_thinking=on_thinking,
150
+ on_answer_to_thinking=on_answer_to_thinking,
151
+ on_finish=on_finish,
152
+ on_route=changed,
153
+ tools=request.tools,
154
+ supports_model_vision=self._supports_vision,
155
+ retry_sleeps=self.retry_sleeps,
156
+ close_timeout=self.stream_close_timeout,
157
+ )
158
+ return self.model_turn(turn, provider_id=target.provider_id, model=target.model)
159
+
160
+ async def close(self) -> None:
161
+ await self.route.close()
@@ -0,0 +1,22 @@
1
+ """Search provider port for the generic `search` tool."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Awaitable
6
+ from typing import Protocol
7
+
8
+
9
+ class SearchProvider(Protocol):
10
+ """Application-provided search backend.
11
+
12
+ Providers own credentials, service selection, and result formatting. The
13
+ tool only validates arguments and gives providers the original user wording.
14
+ """
15
+
16
+ def search(
17
+ self,
18
+ query: str,
19
+ count: int | None = None,
20
+ *,
21
+ user_question: str | None = None,
22
+ ) -> str | Awaitable[str]: ...
@@ -0,0 +1,75 @@
1
+ """Provider-neutral session state and storage contracts.
2
+
3
+ A session is runtime state, not an application policy: applications own paths,
4
+ formats, names, credentials, retention, and picker/trash behavior.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import copy
10
+ import uuid
11
+ from collections.abc import Mapping
12
+ from dataclasses import dataclass, field
13
+ from typing import Any, Protocol
14
+
15
+ from .types import CancellationToken, Message
16
+
17
+
18
+ def new_session_id() -> str:
19
+ return f"sess-{uuid.uuid4().hex}"
20
+
21
+
22
+ @dataclass
23
+ class RuntimeSession:
24
+ """The minimal state needed to continue one conversation."""
25
+
26
+ id: str = field(default_factory=new_session_id)
27
+ messages: list[Message] = field(default_factory=list)
28
+ metadata: dict[str, Any] = field(default_factory=dict)
29
+
30
+ def clone(self) -> RuntimeSession:
31
+ """Snapshot this session without sharing mutable message/state objects."""
32
+
33
+ return RuntimeSession(
34
+ id=self.id,
35
+ messages=copy.deepcopy(self.messages),
36
+ metadata=copy.deepcopy(self.metadata),
37
+ )
38
+
39
+
40
+ class SessionStore(Protocol):
41
+ """Storage backend contract; implementations choose sync/async and format."""
42
+
43
+ async def load(self, session_id: str) -> RuntimeSession: ...
44
+
45
+ async def save(self, session: RuntimeSession) -> None: ...
46
+
47
+
48
+ class MemorySessionStore:
49
+ """Small in-memory SessionStore for tests, examples, and ephemeral agents."""
50
+
51
+ def __init__(self, sessions: Mapping[str, RuntimeSession] | None = None) -> None:
52
+ self._sessions = dict(sessions or {})
53
+
54
+ async def load(self, session_id: str) -> RuntimeSession:
55
+ try:
56
+ return self._sessions[session_id].clone()
57
+ except KeyError:
58
+ raise ValueError(f"unknown session: {session_id}") from None
59
+
60
+ async def save(self, session: RuntimeSession) -> None:
61
+ self._sessions[session.id] = session.clone()
62
+
63
+ def ids(self) -> tuple[str, ...]:
64
+ return tuple(self._sessions)
65
+
66
+
67
+ @dataclass(frozen=True)
68
+ class RunContext:
69
+ """Everything scoped to one invocation of a runtime session."""
70
+
71
+ session: RuntimeSession
72
+ run_id: str
73
+ workspace: Any | None = None
74
+ services: Mapping[str, Any] = field(default_factory=dict)
75
+ cancellation: CancellationToken | None = None
@@ -0,0 +1,190 @@
1
+ """Host shell selection and bounded command execution."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import shutil
7
+ import signal
8
+ import subprocess
9
+ import sys
10
+ import tempfile
11
+ from contextlib import suppress
12
+ from dataclasses import dataclass
13
+ from pathlib import Path
14
+ from typing import Any
15
+
16
+ MAX_BASH_CHARS = 12_000
17
+ _DEFAULT_TIMEOUT = 60
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class Shell:
22
+ """Host shell used by the bash tool and named in an application prompt."""
23
+
24
+ name: str # bash | powershell | cmd
25
+ argv: tuple[str, ...] # prefix; the command string is appended as one arg
26
+
27
+
28
+ _SHELL_HINTS = {
29
+ "bash": "rg, grep, find, ls (POSIX)",
30
+ "powershell": "rg if available, Get-ChildItem, Select-String (PowerShell)",
31
+ "cmd": "dir, findstr; rg if on PATH (cmd.exe)",
32
+ }
33
+
34
+
35
+ def shell_hints(shell: Shell) -> str:
36
+ return _SHELL_HINTS.get(shell.name, shell.name)
37
+
38
+
39
+ def _is_wsl_bash_stub(path: str) -> bool:
40
+ # Windows ships System32\bash.exe as a WSL launcher — skip it for local Git Bash.
41
+ norm = path.replace("/", "\\").lower()
42
+ return norm.endswith("\\system32\\bash.exe") or norm.endswith("\\sysnative\\bash.exe")
43
+
44
+
45
+ def _git_bash_path() -> str | None:
46
+ found = shutil.which("bash")
47
+ if found and not _is_wsl_bash_stub(found):
48
+ return found
49
+ roots = [
50
+ os.environ.get("PROGRAMFILES", r"C:\Program Files"),
51
+ os.environ.get("PROGRAMFILES(X86)", r"C:\Program Files (x86)"),
52
+ os.environ.get("LOCALAPPDATA", ""),
53
+ ]
54
+ for root in roots:
55
+ if not root:
56
+ continue
57
+ for rel in (r"Git\bin\bash.exe", r"Git\usr\bin\bash.exe", r"Programs\Git\bin\bash.exe"):
58
+ cand = Path(root) / rel
59
+ if cand.is_file():
60
+ return str(cand)
61
+ return None
62
+
63
+
64
+ def _shell_for_name(name: str, platform: str) -> Shell:
65
+ if name == "bash":
66
+ if platform == "win32":
67
+ bash = _git_bash_path() or shutil.which("bash") or "bash"
68
+ else:
69
+ bash = shutil.which("bash") or "/bin/bash"
70
+ return Shell("bash", (bash, "-lc"))
71
+ if name == "powershell":
72
+ exe = shutil.which("pwsh") or shutil.which("powershell") or "powershell"
73
+ return Shell("powershell", (exe, "-NoProfile", "-NonInteractive", "-Command"))
74
+ comspec = os.environ.get("COMSPEC", "cmd.exe")
75
+ return Shell("cmd", (comspec, "/c"))
76
+
77
+
78
+ def resolve_shell(*, platform: str | None = None, override: str | None = None) -> Shell:
79
+ """Pick a shell from sys.platform, honoring an explicit executable/name."""
80
+
81
+ plat = sys.platform if platform is None else platform
82
+ if override is None:
83
+ override = os.environ.get("AGENT0_SHELL", "")
84
+ override = override.strip()
85
+ if override:
86
+ key = override.lower()
87
+ if key in ("bash", "powershell", "cmd", "sh"):
88
+ return _shell_for_name("bash" if key == "sh" else key, plat)
89
+ base = Path(override).name.lower()
90
+ if "bash" in base:
91
+ return Shell("bash", (override, "-lc"))
92
+ if base in ("pwsh", "pwsh.exe") or "powershell" in base:
93
+ return Shell("powershell", (override, "-NoProfile", "-NonInteractive", "-Command"))
94
+ return Shell("cmd", (override, "/c"))
95
+ if plat == "win32":
96
+ if bash := _git_bash_path():
97
+ return Shell("bash", (bash, "-lc"))
98
+ if pwsh := shutil.which("pwsh") or shutil.which("powershell"):
99
+ return Shell("powershell", (pwsh, "-NoProfile", "-NonInteractive", "-Command"))
100
+ comspec = os.environ.get("COMSPEC", "cmd.exe")
101
+ return Shell("cmd", (comspec, "/c"))
102
+ bash = shutil.which("bash") or "/bin/bash"
103
+ return Shell("bash", (bash, "-lc"))
104
+
105
+
106
+ _BASH_HEAD_BYTES = MAX_BASH_CHARS * 4 # one char is at most 4 bytes in UTF-8
107
+
108
+
109
+ def _head(f: Any) -> str:
110
+ """First ~MAX_BASH_CHARS chars of a temp file; the rest never enters memory."""
111
+
112
+ f.flush()
113
+ f.seek(0)
114
+ return f.read(_BASH_HEAD_BYTES).decode("utf-8", "replace")
115
+
116
+
117
+ def _process_group_options() -> dict[str, Any]:
118
+ if os.name == "posix":
119
+ return {"start_new_session": True}
120
+ if sys.platform == "win32":
121
+ return {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP}
122
+ return {}
123
+
124
+
125
+ def _kill_process_tree(proc: subprocess.Popen) -> None:
126
+ if os.name == "posix":
127
+ with suppress(ProcessLookupError):
128
+ os.killpg(proc.pid, signal.SIGKILL)
129
+ return
130
+ if sys.platform == "win32":
131
+ with suppress(FileNotFoundError, subprocess.TimeoutExpired):
132
+ subprocess.run(
133
+ ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
134
+ stdout=subprocess.DEVNULL,
135
+ stderr=subprocess.DEVNULL,
136
+ timeout=5,
137
+ check=False,
138
+ )
139
+ if proc.poll() is None:
140
+ proc.kill()
141
+
142
+
143
+ def _truncate(s: str, limit: int, *, tag: str = "truncated") -> str:
144
+ return s if len(s) <= limit else s[:limit] + f"\n...[{tag} {len(s) - limit} chars]"
145
+
146
+
147
+ def run_shell(
148
+ cwd: Path | None,
149
+ command: str,
150
+ timeout: int | None = None,
151
+ *,
152
+ shell: Shell | None = None,
153
+ ) -> str:
154
+ if cwd is None:
155
+ return "error: no workspace is configured"
156
+ selected = shell or resolve_shell()
157
+ env = os.environ.copy()
158
+ env.setdefault("PYTHONIOENCODING", "utf-8")
159
+ env.setdefault("LANG", "C.UTF-8")
160
+ env.setdefault("LC_ALL", "C.UTF-8")
161
+ argv = [*selected.argv, command]
162
+ limit = timeout or _DEFAULT_TIMEOUT
163
+ # Output goes to temp files instead of buffering everything in memory. The
164
+ # shell gets its own process group so a timeout kills its children as well.
165
+ with tempfile.TemporaryFile() as out_f, tempfile.TemporaryFile() as err_f:
166
+ try:
167
+ proc = subprocess.Popen(
168
+ argv,
169
+ cwd=cwd,
170
+ stdout=out_f,
171
+ stderr=err_f,
172
+ env=env,
173
+ **_process_group_options(),
174
+ )
175
+ except FileNotFoundError:
176
+ return f"error: shell not found: {selected.argv[0]}"
177
+ try:
178
+ proc.wait(timeout=limit)
179
+ except subprocess.TimeoutExpired:
180
+ _kill_process_tree(proc)
181
+ proc.wait()
182
+ return _truncate(
183
+ f"timeout after {limit}s\n{_head(out_f)}{_head(err_f)}", MAX_BASH_CHARS
184
+ )
185
+ parts = [f"exit={proc.returncode}"]
186
+ if stdout := _head(out_f):
187
+ parts.append("stdout:\n" + stdout)
188
+ if stderr := _head(err_f):
189
+ parts.append("stderr:\n" + stderr)
190
+ return _truncate("\n".join(parts), MAX_BASH_CHARS)
@@ -0,0 +1,82 @@
1
+ ---
2
+ name: websearch
3
+ description: How to query the search tool well — operators, result triage, and when to read the page instead.
4
+ ---
5
+
6
+ # Web search
7
+
8
+ The `search` tool calls DeepSeek's Search API and returns ranked pages with a
9
+ long `summary`. Read this once per task, before the first search, and search
10
+ according to it.
11
+
12
+ ## When to search
13
+
14
+ - Facts that can have changed since training: releases, versions, APIs, prices,
15
+ changelogs, CVEs, "is X still maintained", "which library should I use in 2026".
16
+ - Error messages and stack traces you cannot explain from the local code.
17
+ - Anything the user frames as current ("latest", "now", "this week", a date).
18
+
19
+ Do **not** search for things the repo already answers: file contents, configs,
20
+ dependency lists, git history. `read` / `bash` are cheaper and authoritative.
21
+ A wrong local answer beats a plausible web answer — check the workspace first.
22
+
23
+ ## Writing the query
24
+
25
+ The tool passes search syntax straight through. `query` must be 1-128 chars.
26
+
27
+ | Operator | Example | Effect |
28
+ |---|---|---|
29
+ | `site:` | `rfc site:github.com OR site:datatracker.ietf.org` | restrict to sites |
30
+ | `-site:` | `grpc -site:medium.com` | exclude sites |
31
+ | `"..."` | `"context deadline exceeded"` | exact phrase |
32
+ | `-` | `python asyncio -tutorial` | exclude a word |
33
+ | `-"..."` | `nginx -"release notes"` | exclude a phrase |
34
+ | `lang:` | `lang:zh` / `lang:zh,en` | restrict language |
35
+ | `after:` / `before:` | `after:2025-01-01` | restrict publish date |
36
+
37
+ Rules of thumb:
38
+
39
+ - Put the exact error string or API name in quotes; drop filler words.
40
+ - Add `after:<year>` when recency matters, and `site:` when you know the
41
+ authority (official docs, GitHub, an RFC, a vendor changelog).
42
+ - Search once per question, not once per sentence. Two or three queries with
43
+ different angles beat eight near-duplicates.
44
+ - `count` defaults to 8; it does not change the price, so do not shrink it.
45
+
46
+ ## Reading the results
47
+
48
+ Each result line carries `score` (relevance, 0-3), `authority` (0-4, `-1`
49
+ unknown), a date, and the site name. The body is a summary, not the page.
50
+
51
+ - Trust `score >= 1.5`; below that the tool already hides results, and a
52
+ "showing the top N" note means nothing matched well — rephrase instead of
53
+ trusting the leftovers.
54
+ - Prefer `authority >= 3` for factual claims; a blog post and an official doc
55
+ that disagree resolve in the doc's favour.
56
+ - Check dates against the question. An undated page about a fast-moving API is
57
+ a liability; an `after:` operator usually fixes the query.
58
+ - When two results contradict each other, say so in the answer instead of
59
+ silently picking one.
60
+
61
+ ## From results to the page
62
+
63
+ `search` returns summaries. Call `fetch` on a URL when you need the exact
64
+ wording of an API signature, a config key, a table, or a code sample — that is
65
+ cheaper and more accurate than searching again.
66
+
67
+ Fetch one or two URLs, not all of them: 5-8 pages of full text will crowd out
68
+ the code you are actually editing. If `fetch` reports no readable text (JS-only
69
+ pages, paywalls, 403), rely on the summary or find another source.
70
+
71
+ ## Failures
72
+
73
+ - `no results` — retry once with fewer operators and shorter phrasing; if the
74
+ second try is empty, answer from what you have and say the search was empty.
75
+ - `402` — the account has no balance. Stop searching and tell the user; do not
76
+ retry.
77
+ - `429` or `5xx` — the tool already retried. Wait, do the local work first, then
78
+ search again. Search is limited to 100 requests/s per account and `fetch` to
79
+ 25/s, and per-domain fetch limits are tighter still.
80
+
81
+ Search and fetch are billed per successful request (only when results come
82
+ back), so a precise query is the cheap one.