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.
- agent0_runtime/__init__.py +172 -0
- agent0_runtime/backend.py +78 -0
- agent0_runtime/builtin_tools.py +200 -0
- agent0_runtime/capabilities.py +50 -0
- agent0_runtime/client.py +69 -0
- agent0_runtime/credentials.py +85 -0
- agent0_runtime/events.py +151 -0
- agent0_runtime/filesystem.py +243 -0
- agent0_runtime/history.py +155 -0
- agent0_runtime/images.py +167 -0
- agent0_runtime/lifecycle.py +194 -0
- agent0_runtime/loop.py +588 -0
- agent0_runtime/managed.py +78 -0
- agent0_runtime/openai_backend.py +433 -0
- agent0_runtime/plugins.py +141 -0
- agent0_runtime/providers.py +95 -0
- agent0_runtime/py.typed +0 -0
- agent0_runtime/responses.py +267 -0
- agent0_runtime/routing.py +335 -0
- agent0_runtime/routing_backend.py +161 -0
- agent0_runtime/search.py +22 -0
- agent0_runtime/session.py +75 -0
- agent0_runtime/shell.py +190 -0
- agent0_runtime/skills/websearch/SKILL.md +82 -0
- agent0_runtime/tools.py +335 -0
- agent0_runtime/types.py +153 -0
- agent0_runtime/web_fetch.py +285 -0
- agent0_runtime/web_search.py +295 -0
- agent0_runtime-0.1.0.dist-info/METADATA +102 -0
- agent0_runtime-0.1.0.dist-info/RECORD +32 -0
- agent0_runtime-0.1.0.dist-info/WHEEL +4 -0
- agent0_runtime-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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()
|
agent0_runtime/search.py
ADDED
|
@@ -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
|
agent0_runtime/shell.py
ADDED
|
@@ -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.
|