mercury-cli-sdk 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.
- mercury_cli_sdk/__init__.py +14 -0
- mercury_cli_sdk/client.py +538 -0
- mercury_cli_sdk/errors.py +77 -0
- mercury_cli_sdk/executable.py +90 -0
- mercury_cli_sdk/framing.py +26 -0
- mercury_cli_sdk/generated.py +1656 -0
- mercury_cli_sdk/helpers.py +234 -0
- mercury_cli_sdk/parse.py +219 -0
- mercury_cli_sdk/py.typed +0 -0
- mercury_cli_sdk/runner.py +489 -0
- mercury_cli_sdk/structured.py +127 -0
- mercury_cli_sdk/support.py +53 -0
- mercury_cli_sdk/sync.py +168 -0
- mercury_cli_sdk/testing.py +194 -0
- mercury_cli_sdk/version.py +1 -0
- mercury_cli_sdk-0.1.0.dist-info/METADATA +161 -0
- mercury_cli_sdk-0.1.0.dist-info/RECORD +19 -0
- mercury_cli_sdk-0.1.0.dist-info/WHEEL +4 -0
- mercury_cli_sdk-0.1.0.dist-info/licenses/LICENSE +202 -0
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"""Mercury CLI SDK: typed clients for ``mercury run`` (rows) and ``mercury runner`` (hosted JSON-RPC sessions)."""
|
|
2
|
+
from .generated import *
|
|
3
|
+
from .generated import __all__ as _generated_exports
|
|
4
|
+
from .errors import Door, MercuryError, MercuryRefusal, MercuryUsageError, MercuryExitError, MercurySpawnError, MercuryWireError, RunExit
|
|
5
|
+
from .parse import Issue, PromptContent, PromptInput, RowRead, StreamRow, UnknownRow, assert_completed, is_input_row_type, is_main_thread, is_outcome, is_retryable_outcome, is_row_type, is_session_row, main_thread_step, outcome_error_text, outcome_failed, turn_opened, turn_waiting, validate, row_of, parse_row, input_row_of
|
|
6
|
+
from .client import ConnectKwargs, Listener, RunKwargs, RunOptions, MercuryRun, TypedRun, argv_of, run
|
|
7
|
+
from .runner import ReadTextFileHandler, WriteTextFileHandler, ElicitationHandler, HostHandler, MercurySession, PermissionHandler, RequestContext, connect, prewarm
|
|
8
|
+
from .sync import RunResult, SyncSession, connect_sync, run_sync
|
|
9
|
+
from .helpers import allow_permission, deny_permission, text_block, image_block, AgentDefinition, ToolDefinition, ToolContext, ToolResult, ToolServer, define_agent, define_tool, serve_tools
|
|
10
|
+
from .version import __version__
|
|
11
|
+
from .structured import StructuredSchema, TypedRunResult, structured_schema, MercurySchemaError, schema_problem, schema_refusal, validate_outcome
|
|
12
|
+
from .support import FEATURE_FLOORS, RunnerFeature, RunnerSupport, compare_versions, parse_version, runner_support
|
|
13
|
+
|
|
14
|
+
__all__ = [*_generated_exports, 'Door', 'MercuryError', 'MercuryRefusal', 'MercuryUsageError', 'MercuryExitError', 'MercurySpawnError', 'MercuryWireError', 'RunExit', 'Issue', 'PromptContent', 'PromptInput', 'RowRead', 'StreamRow', 'UnknownRow', 'assert_completed', 'is_input_row_type', 'is_main_thread', 'is_outcome', 'is_retryable_outcome', 'is_row_type', 'is_session_row', 'main_thread_step', 'outcome_error_text', 'outcome_failed', 'turn_opened', 'turn_waiting', 'validate', 'row_of', 'parse_row', 'input_row_of', 'Listener', 'ConnectKwargs', 'RunKwargs', 'StructuredSchema', 'TypedRunResult', 'structured_schema', 'MercurySchemaError', 'schema_problem', 'schema_refusal', 'validate_outcome', 'FEATURE_FLOORS', 'RunnerFeature', 'RunnerSupport', 'compare_versions', 'parse_version', 'runner_support', 'TypedRun', 'RunOptions', 'MercuryRun', 'argv_of', 'run', 'ReadTextFileHandler', 'WriteTextFileHandler', 'ElicitationHandler', 'HostHandler', 'MercurySession', 'PermissionHandler', 'RequestContext', 'connect', 'prewarm', 'RunResult', 'SyncSession', 'connect_sync', 'run_sync', 'allow_permission', 'deny_permission', 'text_block', 'image_block', 'AgentDefinition', 'ToolDefinition', 'ToolContext', 'ToolResult', 'ToolServer', 'define_agent', 'define_tool', 'serve_tools', '__version__']
|
|
@@ -0,0 +1,538 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
import asyncio
|
|
3
|
+
import atexit
|
|
4
|
+
import codecs
|
|
5
|
+
from datetime import datetime, timezone
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
import signal
|
|
9
|
+
import time
|
|
10
|
+
from dataclasses import dataclass, field, replace
|
|
11
|
+
from typing import Any, Callable, AsyncIterable, AsyncIterator, Literal, Generic, TypedDict, TypeVar, Unpack, cast, overload
|
|
12
|
+
from .errors import MercuryError, MercuryExitError, MercuryRefusal, MercurySpawnError, MercuryUsageError, MercuryWireError, RunExit
|
|
13
|
+
from .generated import InputRow, OutcomeRow, SessionRow, TypedOutcome, MAX_LINE_BYTES, PermissionMode, EffortLevel, InputBlock
|
|
14
|
+
from .framing import read_lines
|
|
15
|
+
from .executable import executable_of
|
|
16
|
+
from .structured import StructuredSchema, schema_object, validate_outcome
|
|
17
|
+
from .helpers import ToolDefinition, ToolServer, serve_tools
|
|
18
|
+
from .parse import Issue, StreamRow, cap_queue, cap_rows, clear_queue, parse_row, input_row_of
|
|
19
|
+
|
|
20
|
+
Listener = Callable[[Any], object]
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass
|
|
24
|
+
class RunOptions:
|
|
25
|
+
"""Everything ``run()`` and ``connect()`` accept; each field is one ``mercury run`` option (``continue_`` is ``--continue``)."""
|
|
26
|
+
worktree: bool | str = False
|
|
27
|
+
reasoning_mode: Literal['enabled', 'adaptive', 'disabled'] | None = None
|
|
28
|
+
brief_file: str | None = None
|
|
29
|
+
brief_add_file: str | None = None
|
|
30
|
+
debug: bool | str = False
|
|
31
|
+
replay_to: str | None = None
|
|
32
|
+
restore_files: str | None = None
|
|
33
|
+
tools: list[ToolDefinition] = field(default_factory=list)
|
|
34
|
+
auto_allow_tools: bool = True
|
|
35
|
+
prompt: str | list[InputBlock] | AsyncIterable[str | InputRow] | None = None
|
|
36
|
+
cancel: asyncio.Event | None = None
|
|
37
|
+
mercury: str | list[str] | None = None
|
|
38
|
+
cwd: str | None = None
|
|
39
|
+
env: dict[str, str] | None = None
|
|
40
|
+
input: Literal['rows'] | None = None
|
|
41
|
+
stdin: str | None = None
|
|
42
|
+
project: str | None = None
|
|
43
|
+
model: str | None = None
|
|
44
|
+
effort: EffortLevel | None = None
|
|
45
|
+
mode: PermissionMode | None = None
|
|
46
|
+
agent: str | None = None
|
|
47
|
+
agent_defs: dict[str, Any] | None = None
|
|
48
|
+
backup_model: str | None = None
|
|
49
|
+
sovereign: bool = False
|
|
50
|
+
allow_sovereign: bool = False
|
|
51
|
+
allowed_tools: list[str] = field(default_factory=list)
|
|
52
|
+
block_tools: list[str] = field(default_factory=list)
|
|
53
|
+
toolset: list[str] = field(default_factory=list)
|
|
54
|
+
mcp: list[str] = field(default_factory=list)
|
|
55
|
+
only_mcp: bool = False
|
|
56
|
+
brief: str | None = None
|
|
57
|
+
brief_add: str | None = None
|
|
58
|
+
schema: str | dict[str, Any] | StructuredSchema[Any] | None = None
|
|
59
|
+
max_turns: int | None = None
|
|
60
|
+
max_rows: int | None = None
|
|
61
|
+
max_time: str | None = None
|
|
62
|
+
budget_usd: float | None = None
|
|
63
|
+
partial: bool = False
|
|
64
|
+
config: str | dict[str, Any] | None = None
|
|
65
|
+
config_layers: list[str] | None = None
|
|
66
|
+
extensions: list[str] = field(default_factory=list)
|
|
67
|
+
session_id: str | None = None
|
|
68
|
+
title: str | None = None
|
|
69
|
+
resume: str | None = None
|
|
70
|
+
continue_: bool = False
|
|
71
|
+
fork: bool = False
|
|
72
|
+
ephemeral: bool = False
|
|
73
|
+
lean: bool = False
|
|
74
|
+
advise: bool = False
|
|
75
|
+
no_commands: bool = False
|
|
76
|
+
provider_preview: list[str] = field(default_factory=list)
|
|
77
|
+
log_file: str | None = None
|
|
78
|
+
extra_args: list[str] = field(default_factory=list)
|
|
79
|
+
on_stderr: Callable[[str], object] | None = None
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
class ConnectKwargs(TypedDict, total=False):
|
|
83
|
+
"""The ``RunOptions`` fields ``connect``, ``connect_sync`` and ``prewarm`` accept as keywords; ``schema`` is a named parameter."""
|
|
84
|
+
worktree: bool | str
|
|
85
|
+
reasoning_mode: Literal['enabled', 'adaptive', 'disabled'] | None
|
|
86
|
+
brief_file: str | None
|
|
87
|
+
brief_add_file: str | None
|
|
88
|
+
debug: bool | str
|
|
89
|
+
replay_to: str | None
|
|
90
|
+
restore_files: str | None
|
|
91
|
+
tools: list[ToolDefinition]
|
|
92
|
+
auto_allow_tools: bool
|
|
93
|
+
mercury: str | list[str] | None
|
|
94
|
+
cwd: str | None
|
|
95
|
+
env: dict[str, str] | None
|
|
96
|
+
project: str | None
|
|
97
|
+
model: str | None
|
|
98
|
+
effort: EffortLevel | None
|
|
99
|
+
mode: PermissionMode | None
|
|
100
|
+
agent: str | None
|
|
101
|
+
agent_defs: dict[str, Any] | None
|
|
102
|
+
backup_model: str | None
|
|
103
|
+
sovereign: bool
|
|
104
|
+
allow_sovereign: bool
|
|
105
|
+
allowed_tools: list[str]
|
|
106
|
+
block_tools: list[str]
|
|
107
|
+
toolset: list[str]
|
|
108
|
+
mcp: list[str]
|
|
109
|
+
only_mcp: bool
|
|
110
|
+
brief: str | None
|
|
111
|
+
brief_add: str | None
|
|
112
|
+
max_turns: int | None
|
|
113
|
+
max_rows: int | None
|
|
114
|
+
max_time: str | None
|
|
115
|
+
budget_usd: float | None
|
|
116
|
+
partial: bool
|
|
117
|
+
config: str | dict[str, Any] | None
|
|
118
|
+
config_layers: list[str] | None
|
|
119
|
+
extensions: list[str]
|
|
120
|
+
session_id: str | None
|
|
121
|
+
title: str | None
|
|
122
|
+
resume: str | None
|
|
123
|
+
continue_: bool
|
|
124
|
+
fork: bool
|
|
125
|
+
ephemeral: bool
|
|
126
|
+
lean: bool
|
|
127
|
+
advise: bool
|
|
128
|
+
no_commands: bool
|
|
129
|
+
provider_preview: list[str]
|
|
130
|
+
log_file: str | None
|
|
131
|
+
extra_args: list[str]
|
|
132
|
+
on_stderr: Callable[[str], object] | None
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
class RunKwargs(ConnectKwargs, total=False):
|
|
136
|
+
"""The ``RunOptions`` fields ``run`` and ``run_sync`` accept as keywords beside ``prompt`` and ``schema``."""
|
|
137
|
+
cancel: asyncio.Event | None
|
|
138
|
+
input: Literal['rows'] | None
|
|
139
|
+
stdin: str | None
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def argv_of(options: RunOptions, door: Literal['run', 'runner'] = 'run') -> list[str]:
|
|
143
|
+
"""The exact command line ``run()`` would start for these options."""
|
|
144
|
+
if options.prompt is not None and not isinstance(options.prompt, str): options = replace(options, input='rows')
|
|
145
|
+
args = executable_of(options.mercury, options.env, options.cwd)
|
|
146
|
+
if options.project is not None: args += ['--project', options.project]
|
|
147
|
+
args += ['run', '--format', 'rows'] if door == 'run' else ['runner']
|
|
148
|
+
values = ['model', 'effort', 'mode', 'agent', 'backup_model', 'brief', 'brief_add', 'max_turns', 'max_time', 'session_id', 'title', 'resume', 'log_file', 'input', 'replay_to', 'restore_files', 'reasoning_mode', 'brief_file', 'brief_add_file']
|
|
149
|
+
for name in values:
|
|
150
|
+
value = getattr(options, name)
|
|
151
|
+
if value is not None: args += ['--' + name.replace('_', '-'), str(value)]
|
|
152
|
+
if options.budget_usd is not None: args += ['--budget', str(options.budget_usd)]
|
|
153
|
+
for name in ['sovereign', 'allow_sovereign', 'only_mcp', 'partial', 'continue_', 'fork', 'ephemeral', 'lean', 'advise', 'no_commands']:
|
|
154
|
+
if getattr(options, name): args.append('--' + name.rstrip('_').replace('_', '-'))
|
|
155
|
+
for name in ['allowed_tools', 'block_tools', 'toolset', 'mcp', 'provider_preview']:
|
|
156
|
+
if getattr(options, name): args += ['--' + name.replace('_', '-'), *getattr(options, name)]
|
|
157
|
+
for name in ['schema', 'config', 'agent_defs']:
|
|
158
|
+
value = getattr(options, name)
|
|
159
|
+
if name == 'schema' and value is not None: value = schema_object(value, options.cwd)
|
|
160
|
+
if value is not None: args += ['--' + name.replace('_', '-'), value if isinstance(value, str) else json.dumps(value)]
|
|
161
|
+
if options.config_layers is not None: args += ['--config-layers', ','.join(options.config_layers)]
|
|
162
|
+
for extension in options.extensions: args += ['--extension', extension]
|
|
163
|
+
for name in ['worktree', 'debug']:
|
|
164
|
+
value = getattr(options, name)
|
|
165
|
+
if value is True: args.append('--' + name)
|
|
166
|
+
elif isinstance(value, str): args += ['--' + name, value]
|
|
167
|
+
args += options.extra_args
|
|
168
|
+
if isinstance(options.prompt, str): args += ['--', options.prompt]
|
|
169
|
+
return args
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
_live: dict[int, asyncio.subprocess.Process] = {}
|
|
173
|
+
_sent: dict[int, str] = {}
|
|
174
|
+
_owner_pid = os.getpid()
|
|
175
|
+
WINDOWS = os.name == 'nt'
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def _reset_after_fork() -> None:
|
|
179
|
+
global _owner_pid
|
|
180
|
+
_owner_pid = os.getpid()
|
|
181
|
+
_live.clear()
|
|
182
|
+
_sent.clear()
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def _end_live_children() -> None:
|
|
186
|
+
if os.getpid() != _owner_pid: return
|
|
187
|
+
for pid, child in list(_live.items()):
|
|
188
|
+
if child.returncode is None:
|
|
189
|
+
try: os.kill(pid, signal.SIGTERM)
|
|
190
|
+
except OSError: pass
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
atexit.register(_end_live_children)
|
|
194
|
+
if hasattr(os, 'register_at_fork'): os.register_at_fork(after_in_child=_reset_after_fork)
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def track(child: asyncio.subprocess.Process) -> None:
|
|
198
|
+
if child.pid is not None:
|
|
199
|
+
_live[child.pid] = child
|
|
200
|
+
_sent.pop(child.pid, None)
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
def untrack(child: asyncio.subprocess.Process) -> None:
|
|
204
|
+
_live.pop(child.pid, None)
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def send_signal(child: asyncio.subprocess.Process, name: Literal['SIGINT', 'SIGTERM', 'SIGKILL']) -> None:
|
|
208
|
+
"""Send the named signal; on Windows, which delivers none, end the process as Node's child_process does and report the name in the exit receipt."""
|
|
209
|
+
if child.returncode is not None: return
|
|
210
|
+
try:
|
|
211
|
+
if not WINDOWS: child.send_signal(getattr(signal, name))
|
|
212
|
+
elif name == 'SIGKILL': child.kill()
|
|
213
|
+
else: child.terminate()
|
|
214
|
+
except ProcessLookupError: return
|
|
215
|
+
if child.pid is not None: _sent[child.pid] = name
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def exit_of(child: asyncio.subprocess.Process, code: int, stderr: str) -> RunExit:
|
|
219
|
+
"""The exit receipt: the signal that ended the child, or its code; on Windows a child the package ended reports the signal it sent."""
|
|
220
|
+
sent = _sent.pop(child.pid, None) if child.pid is not None else None
|
|
221
|
+
if code < 0 and not WINDOWS:
|
|
222
|
+
try: name = signal.Signals(-code).name
|
|
223
|
+
except ValueError: name = f'SIG{-code}'
|
|
224
|
+
return RunExit(None, name, stderr)
|
|
225
|
+
if WINDOWS and sent is not None and code == 1: return RunExit(None, sent, stderr)
|
|
226
|
+
return RunExit(code, None, stderr)
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
_USAGE_KEYS = ('input_tokens', 'cached_input_tokens', 'cache_write_input_tokens', 'output_tokens')
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
def interrupted_outcome(rows: list[StreamRow], started_at: float, now: float | None = None) -> OutcomeRow:
|
|
233
|
+
"""The outcome row of a turn the package interrupted when the child ended by the signal before writing its own."""
|
|
234
|
+
at = time.time() if now is None else now
|
|
235
|
+
opened = [row for row in rows if row['type'] == 'turn' and row.get('state') == 'started' and 'parent_call_id' not in row]
|
|
236
|
+
turn = opened[-1] if opened else None
|
|
237
|
+
steps = [row for row in rows if row['type'] == 'step' and 'parent_call_id' not in row and (turn is None or row.get('seq', 0) > turn.get('seq', 0))]
|
|
238
|
+
usage: dict[str, int] = dict.fromkeys(_USAGE_KEYS, 0)
|
|
239
|
+
models: dict[str, dict[str, int]] = {}
|
|
240
|
+
for step in steps:
|
|
241
|
+
model = models.setdefault(str(step.get('model')), {**dict.fromkeys(_USAGE_KEYS, 0), 'web_searches': 0})
|
|
242
|
+
for key in _USAGE_KEYS:
|
|
243
|
+
usage[key] += int(step['usage'][key])
|
|
244
|
+
model[key] += int(step['usage'][key])
|
|
245
|
+
if 'reasoning_output_tokens' in step['usage']:
|
|
246
|
+
reasoning = int(step['usage']['reasoning_output_tokens'])
|
|
247
|
+
usage['reasoning_output_tokens'] = usage.get('reasoning_output_tokens', 0) + reasoning
|
|
248
|
+
model['reasoning_output_tokens'] = model.get('reasoning_output_tokens', 0) + reasoning
|
|
249
|
+
last = rows[-1] if rows else None
|
|
250
|
+
started = datetime.fromisoformat(str(turn['timestamp']).replace('Z', '+00:00')).timestamp() if turn else started_at
|
|
251
|
+
row = {'type': 'outcome', 'seq': int(last.get('seq', 0) if last else 0) + 1, 'timestamp': datetime.fromtimestamp(at, timezone.utc).isoformat(timespec='milliseconds').replace('+00:00', 'Z'), 'session_id': str(last.get('session_id', '')) if last else '', 'turn': int(turn.get('turn', max(1, len(opened)))) if turn else max(1, len(opened)), 'schema': 1, 'turn_id': str(turn['turn_id']) if turn else '', 'status': 'interrupted', 'error': {'message': 'Interrupted', 'class': 'interrupt'}, 'steps': len(steps), 'wall_ms': max(0, int((at - started) * 1000)), 'usage': usage, 'models': models, 'denials': []}
|
|
252
|
+
return cast(OutcomeRow, row)
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
async def end_child(child: asyncio.subprocess.Process) -> int:
|
|
256
|
+
"""Terminate a child that must not go on, escalating to SIGKILL after a second, and return its exit code."""
|
|
257
|
+
send_signal(child, 'SIGTERM')
|
|
258
|
+
try: return await asyncio.wait_for(asyncio.shield(child.wait()), 1)
|
|
259
|
+
except asyncio.TimeoutError:
|
|
260
|
+
send_signal(child, 'SIGKILL')
|
|
261
|
+
return await child.wait()
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
async def spawn(args: list[str], options: RunOptions) -> asyncio.subprocess.Process:
|
|
265
|
+
if options.cwd is not None and not os.path.isdir(options.cwd): raise MercurySpawnError(args[0], f'the working directory does not exist: {options.cwd}')
|
|
266
|
+
try:
|
|
267
|
+
child = await asyncio.create_subprocess_exec(*args, cwd=options.cwd, env=options.env, stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, limit=MAX_LINE_BYTES)
|
|
268
|
+
except OSError as error:
|
|
269
|
+
raise MercurySpawnError(args[0], error) from error
|
|
270
|
+
track(child)
|
|
271
|
+
return child
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
async def read_stderr(handle: Any) -> None:
|
|
275
|
+
"""Append the child's standard error to ``handle.stderr`` as it arrives, emitting each decoded chunk as ``'stderr'`` and to ``on_stderr``."""
|
|
276
|
+
decoder = codecs.getincrementaldecoder('utf-8')(errors='replace')
|
|
277
|
+
pending = ''
|
|
278
|
+
def deliver(text: str, final: bool = False) -> None:
|
|
279
|
+
nonlocal pending
|
|
280
|
+
joined = pending + text
|
|
281
|
+
pending = '' if final or not joined.endswith('\r') else '\r'
|
|
282
|
+
delivered = joined[:len(joined) - len(pending)].replace('\r\n', '\n')
|
|
283
|
+
if not delivered: return
|
|
284
|
+
handle.stderr += delivered
|
|
285
|
+
handle._emit('stderr', delivered)
|
|
286
|
+
if handle.options.on_stderr is not None: handle.options.on_stderr(delivered)
|
|
287
|
+
while chunk := await handle._stderr.read(65536): deliver(decoder.decode(chunk))
|
|
288
|
+
deliver(decoder.decode(b'', final=True), True)
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
class MercuryRun:
|
|
292
|
+
"""One ``mercury run`` process: an async iterator of its rows, with ``outcome``, ``session`` and ``exit`` awaitable."""
|
|
293
|
+
def __init__(self, child: asyncio.subprocess.Process, options: RunOptions, tools: ToolServer | None = None):
|
|
294
|
+
self._tools = tools
|
|
295
|
+
self.child = child
|
|
296
|
+
assert child.stdin is not None and child.stdout is not None and child.stderr is not None
|
|
297
|
+
self._stdin = child.stdin
|
|
298
|
+
self._stdout = child.stdout
|
|
299
|
+
self._stderr = child.stderr
|
|
300
|
+
self.options = options
|
|
301
|
+
self.rows: list[StreamRow] = []
|
|
302
|
+
self.stderr = ''
|
|
303
|
+
self.error: MercuryError | None = None
|
|
304
|
+
loop = asyncio.get_running_loop()
|
|
305
|
+
self.outcome: asyncio.Future[OutcomeRow] = loop.create_future()
|
|
306
|
+
self.session: asyncio.Future[SessionRow] = loop.create_future()
|
|
307
|
+
self.exit: asyncio.Future[RunExit] = loop.create_future()
|
|
308
|
+
for future in (self.outcome, self.session): future.add_done_callback(lambda f: None if f.cancelled() else f.exception())
|
|
309
|
+
self._listeners: dict[str, list[Listener]] = {}
|
|
310
|
+
self._queue: asyncio.Queue[StreamRow | None] = asyncio.Queue()
|
|
311
|
+
self._input_task: asyncio.Task[None] | None = None
|
|
312
|
+
self._interrupt_requested = False
|
|
313
|
+
self._interrupt_sent = False
|
|
314
|
+
self._started_at = time.time()
|
|
315
|
+
self._sent = 0
|
|
316
|
+
self._reader = asyncio.create_task(self._read())
|
|
317
|
+
self._cancel_task = asyncio.create_task(self._watch_cancel(options.cancel)) if options.cancel is not None else None
|
|
318
|
+
|
|
319
|
+
def on(self, type: str, listener: Listener) -> MercuryRun:
|
|
320
|
+
"""Listen for one row type, ``'row'`` (every row), ``'error'`` or ``'end'``."""
|
|
321
|
+
self._listeners.setdefault(type, []).append(listener)
|
|
322
|
+
return self
|
|
323
|
+
|
|
324
|
+
def off(self, type: str, listener: Listener) -> MercuryRun:
|
|
325
|
+
if listener in self._listeners.get(type, []): self._listeners[type].remove(listener)
|
|
326
|
+
return self
|
|
327
|
+
|
|
328
|
+
def _emit(self, type: str, value: Any) -> None:
|
|
329
|
+
for listener in tuple(self._listeners.get(type, [])): listener(value)
|
|
330
|
+
|
|
331
|
+
async def _watch_cancel(self, event: asyncio.Event) -> None:
|
|
332
|
+
try:
|
|
333
|
+
await event.wait()
|
|
334
|
+
self.interrupt()
|
|
335
|
+
except asyncio.CancelledError: pass
|
|
336
|
+
|
|
337
|
+
async def _read(self) -> None:
|
|
338
|
+
stderr = asyncio.create_task(read_stderr(self))
|
|
339
|
+
last: OutcomeRow | None = None
|
|
340
|
+
try:
|
|
341
|
+
async for line in read_lines(self._stdout):
|
|
342
|
+
if not line.strip(): continue
|
|
343
|
+
read = parse_row(line)
|
|
344
|
+
if not read.ok:
|
|
345
|
+
raise MercuryWireError(line, read.reason or 'invalid', read.type, read.issues)
|
|
346
|
+
row = read.row
|
|
347
|
+
assert row is not None
|
|
348
|
+
self.rows.append(row)
|
|
349
|
+
cap_rows(self.rows, self.options.max_rows)
|
|
350
|
+
if row['type'] == 'session' and not self.session.done():
|
|
351
|
+
self.session.set_result(row)
|
|
352
|
+
if self._interrupt_requested: self.interrupt()
|
|
353
|
+
if row['type'] == 'outcome': last = row
|
|
354
|
+
self._queue.put_nowait(row)
|
|
355
|
+
cap_queue(self._queue, self.options.max_rows)
|
|
356
|
+
self._emit('row', row)
|
|
357
|
+
self._emit(row['type'], row)
|
|
358
|
+
except Exception as error:
|
|
359
|
+
self.error = error if isinstance(error, MercuryError) else MercuryWireError('', 'invalid', issues=[Issue('', str(error))])
|
|
360
|
+
self._stdin.close()
|
|
361
|
+
await end_child(self.child)
|
|
362
|
+
code = await self.child.wait()
|
|
363
|
+
untrack(self.child)
|
|
364
|
+
if self._tools: await self._tools.close()
|
|
365
|
+
await stderr
|
|
366
|
+
exit = exit_of(self.child, code, self.stderr)
|
|
367
|
+
if self.error is None and last is None and self._interrupt_sent and (exit.signal == 'SIGINT' or exit.code == 130):
|
|
368
|
+
last = interrupted_outcome(self.rows, self._started_at)
|
|
369
|
+
self.rows.append(last)
|
|
370
|
+
self._queue.put_nowait(last)
|
|
371
|
+
self._emit('row', last)
|
|
372
|
+
self._emit('outcome', last)
|
|
373
|
+
if self.error is None:
|
|
374
|
+
if last and last['status'] == 'refused': self.error = MercuryRefusal(last, exit)
|
|
375
|
+
elif last is None: self.error = MercuryUsageError(exit) if code == 2 else MercuryExitError(exit, 'run', 'no input row was sent before stdin was closed' if self.options.input == 'rows' and self._sent == 0 and not self.rows else None)
|
|
376
|
+
if self.error is None and last is not None:
|
|
377
|
+
try: last = validate_outcome(last, self.options.schema, self.options.cwd)
|
|
378
|
+
except Exception as error: self.error = error if isinstance(error, MercuryError) else MercuryError(str(error), exit)
|
|
379
|
+
if self.error:
|
|
380
|
+
self.error.exit = exit
|
|
381
|
+
self.outcome.set_exception(self.error)
|
|
382
|
+
if not self.session.done(): self.session.set_exception(self.error)
|
|
383
|
+
self._emit('error', self.error)
|
|
384
|
+
else:
|
|
385
|
+
assert last is not None
|
|
386
|
+
self.outcome.set_result(last)
|
|
387
|
+
if not self.session.done(): self.session.set_exception(MercuryExitError(exit))
|
|
388
|
+
self.exit.set_result(exit)
|
|
389
|
+
if self._cancel_task: self._cancel_task.cancel()
|
|
390
|
+
if self._input_task: self._input_task.cancel()
|
|
391
|
+
self._queue.put_nowait(None)
|
|
392
|
+
self._emit('end', exit)
|
|
393
|
+
|
|
394
|
+
async def _feed(self, prompt: list[InputBlock] | AsyncIterable[str | InputRow]) -> None:
|
|
395
|
+
try:
|
|
396
|
+
if isinstance(prompt, list): await self.send_prompt(prompt)
|
|
397
|
+
else:
|
|
398
|
+
async for row in prompt:
|
|
399
|
+
if self.exit.done(): break
|
|
400
|
+
await self.send({'type': 'prompt', 'content': row} if isinstance(row, str) else row)
|
|
401
|
+
self.close_input()
|
|
402
|
+
except asyncio.CancelledError: raise
|
|
403
|
+
except Exception as error:
|
|
404
|
+
if not self.exit.done():
|
|
405
|
+
self.error = error if isinstance(error, MercuryError) else MercuryError(str(error))
|
|
406
|
+
await end_child(self.child)
|
|
407
|
+
finally:
|
|
408
|
+
close = getattr(prompt, 'aclose', None)
|
|
409
|
+
if close is not None: await close()
|
|
410
|
+
|
|
411
|
+
async def send(self, row: InputRow) -> None:
|
|
412
|
+
"""Write one input row to a run started with ``input='rows'``."""
|
|
413
|
+
if self.exit.done() or self.child.returncode is not None or self.options.input != 'rows' or self._stdin.is_closing(): raise MercuryError('input rows is not open')
|
|
414
|
+
read = input_row_of(row)
|
|
415
|
+
if not read.ok: raise MercuryWireError(json.dumps(row), read.reason or 'invalid', read.type, read.issues)
|
|
416
|
+
try:
|
|
417
|
+
self._stdin.write((json.dumps(row) + '\n').encode())
|
|
418
|
+
await self._stdin.drain()
|
|
419
|
+
self._sent += 1
|
|
420
|
+
except OSError as error: raise MercuryError(str(error), self.exit.result() if self.exit.done() else None) from error
|
|
421
|
+
|
|
422
|
+
async def send_prompt(self, content: str | list[InputBlock], **options: Any) -> None:
|
|
423
|
+
await self.send(cast(InputRow, {**options, 'type': 'prompt', 'content': content}))
|
|
424
|
+
|
|
425
|
+
async def send_shell(self, command: str, **options: Any) -> None:
|
|
426
|
+
await self.send(cast(InputRow, {**options, 'type': 'shell', 'command': command}))
|
|
427
|
+
|
|
428
|
+
async def send_note(self, to: str, content: str, **options: Any) -> None:
|
|
429
|
+
await self.send(cast(InputRow, {**options, 'type': 'note', 'to': to, 'content': content}))
|
|
430
|
+
|
|
431
|
+
def close_input(self) -> None:
|
|
432
|
+
"""End stdin; the run finishes its queued work and exits."""
|
|
433
|
+
self._stdin.close()
|
|
434
|
+
|
|
435
|
+
def clear_rows(self) -> None:
|
|
436
|
+
self.rows.clear()
|
|
437
|
+
clear_queue(self._queue)
|
|
438
|
+
|
|
439
|
+
def interrupt(self) -> None:
|
|
440
|
+
"""End the running turn with SIGINT; before the session row arrives the signal waits for it, so the turn ends as ``interrupted`` rather than killing a booting CLI."""
|
|
441
|
+
if self._tools: self._tools.cancel()
|
|
442
|
+
if self.exit.done(): return
|
|
443
|
+
if not self.session.done():
|
|
444
|
+
self._interrupt_requested = True
|
|
445
|
+
return
|
|
446
|
+
if self.child.returncode is None:
|
|
447
|
+
send_signal(self.child, 'SIGINT')
|
|
448
|
+
self._interrupt_sent = True
|
|
449
|
+
|
|
450
|
+
def terminate(self) -> None:
|
|
451
|
+
"""End the process with SIGTERM (on Windows, terminate it); returns at once, the exit is awaited through ``exit``."""
|
|
452
|
+
send_signal(self.child, 'SIGTERM')
|
|
453
|
+
|
|
454
|
+
def kill(self) -> None:
|
|
455
|
+
"""End the process with SIGKILL (on Windows, terminate it); returns at once, the exit is awaited through ``exit``."""
|
|
456
|
+
send_signal(self.child, 'SIGKILL')
|
|
457
|
+
|
|
458
|
+
async def close(self) -> None:
|
|
459
|
+
"""End stdin and wait for the exit; SIGTERM after five seconds, SIGKILL after ten."""
|
|
460
|
+
self.close_input()
|
|
461
|
+
try: await asyncio.wait_for(asyncio.shield(self.exit), 5)
|
|
462
|
+
except asyncio.TimeoutError:
|
|
463
|
+
self.terminate()
|
|
464
|
+
try: await asyncio.wait_for(asyncio.shield(self.exit), 5)
|
|
465
|
+
except asyncio.TimeoutError:
|
|
466
|
+
self.kill()
|
|
467
|
+
await self.exit
|
|
468
|
+
|
|
469
|
+
async def __aenter__(self) -> MercuryRun:
|
|
470
|
+
return self
|
|
471
|
+
|
|
472
|
+
async def __aexit__(self, *exc: Any) -> None:
|
|
473
|
+
await self.close()
|
|
474
|
+
|
|
475
|
+
def __aiter__(self) -> AsyncIterator[StreamRow]:
|
|
476
|
+
return self
|
|
477
|
+
|
|
478
|
+
async def __anext__(self) -> StreamRow:
|
|
479
|
+
if self.exit.done() and self._queue.empty():
|
|
480
|
+
if self.error: raise self.error
|
|
481
|
+
raise StopAsyncIteration
|
|
482
|
+
row = await self._queue.get()
|
|
483
|
+
if row is None:
|
|
484
|
+
if self.error: raise self.error
|
|
485
|
+
raise StopAsyncIteration
|
|
486
|
+
return row
|
|
487
|
+
|
|
488
|
+
|
|
489
|
+
T = TypeVar('T')
|
|
490
|
+
|
|
491
|
+
|
|
492
|
+
class TypedRun(MercuryRun, Generic[T]):
|
|
493
|
+
outcome: asyncio.Future[TypedOutcome[T]]
|
|
494
|
+
|
|
495
|
+
async def __aenter__(self) -> TypedRun[T]: return self
|
|
496
|
+
|
|
497
|
+
|
|
498
|
+
@overload
|
|
499
|
+
async def run(prompt: str | list[InputBlock] | AsyncIterable[str | InputRow] | None = None, *, schema: StructuredSchema[T], options: RunOptions | None = None, **kwargs: Unpack[RunKwargs]) -> TypedRun[T]: ...
|
|
500
|
+
@overload
|
|
501
|
+
async def run(prompt: str | list[InputBlock] | AsyncIterable[str | InputRow] | None = None, *, schema: str | dict[str, Any] | None = None, options: RunOptions | None = None, **kwargs: Unpack[RunKwargs]) -> MercuryRun: ...
|
|
502
|
+
async def run(prompt: str | list[InputBlock] | AsyncIterable[str | InputRow] | None = None, *, schema: StructuredSchema[Any] | str | dict[str, Any] | None = None, options: RunOptions | None = None, **kwargs: Unpack[RunKwargs]) -> MercuryRun:
|
|
503
|
+
"""Start ``mercury run`` for a prompt (or ``input='rows'`` for streamed input) and return its handle once the process has started."""
|
|
504
|
+
overrides: dict[str, Any] = dict(kwargs)
|
|
505
|
+
if prompt is not None: overrides['prompt'] = prompt
|
|
506
|
+
if schema is not None: overrides['schema'] = schema
|
|
507
|
+
opts = replace(options, **overrides) if options is not None else RunOptions(**overrides)
|
|
508
|
+
if opts.prompt is not None and not isinstance(opts.prompt, str): opts = replace(opts, input='rows')
|
|
509
|
+
if opts.input not in (None, 'rows'): raise MercuryError('input must be rows')
|
|
510
|
+
if opts.input == 'rows' and opts.stdin is not None: raise MercuryError('stdin text cannot be combined with input rows')
|
|
511
|
+
if opts.schema is not None and not isinstance(opts.schema, StructuredSchema): opts = replace(opts, schema=schema_object(opts.schema, opts.cwd))
|
|
512
|
+
opts, tools = await prepare_tools(opts)
|
|
513
|
+
try: child = await spawn(argv_of(opts), opts)
|
|
514
|
+
except BaseException:
|
|
515
|
+
if tools: await tools.close()
|
|
516
|
+
raise
|
|
517
|
+
assert child.stdin is not None
|
|
518
|
+
handle = TypedRun[Any](child, opts, tools)
|
|
519
|
+
if opts.stdin is not None:
|
|
520
|
+
child.stdin.write(opts.stdin.encode())
|
|
521
|
+
await child.stdin.drain()
|
|
522
|
+
if opts.input != 'rows': child.stdin.close()
|
|
523
|
+
if opts.prompt is not None and not isinstance(opts.prompt, str): handle._input_task = asyncio.create_task(handle._feed(opts.prompt))
|
|
524
|
+
return handle
|
|
525
|
+
|
|
526
|
+
|
|
527
|
+
async def prepare_tools(options: RunOptions) -> tuple[RunOptions, ToolServer | None]:
|
|
528
|
+
if not options.tools: return options, None
|
|
529
|
+
server = await serve_tools(options.tools)
|
|
530
|
+
names = [f'mcp__sdk-tools__{tool.name}' for tool in options.tools]
|
|
531
|
+
agents = options.agent_defs
|
|
532
|
+
if options.auto_allow_tools and agents is not None:
|
|
533
|
+
agents = {name: {**agent, 'tools': list(dict.fromkeys([*agent.get('tools', []), *names]))} if isinstance(agent, dict) and isinstance(agent.get('tools'), list) else agent for name, agent in agents.items()}
|
|
534
|
+
return replace(options, mcp=[*options.mcp, server.mcp], allowed_tools=list(dict.fromkeys([*options.allowed_tools, *names])) if options.auto_allow_tools else list(options.allowed_tools), agent_defs=agents), server
|
|
535
|
+
|
|
536
|
+
|
|
537
|
+
def warm_options(options: RunOptions) -> RunOptions:
|
|
538
|
+
return replace(options, env={**(options.env if options.env is not None else os.environ), 'MERCURY_CONCOURSE_WORKER': '1'})
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
from dataclasses import dataclass
|
|
3
|
+
from typing import Any, Literal, Mapping
|
|
4
|
+
from .generated import ErrorClass, OutcomeRow
|
|
5
|
+
from .parse import Issue
|
|
6
|
+
|
|
7
|
+
Door = Literal['run', 'runner']
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
@dataclass(frozen=True)
|
|
11
|
+
class RunExit:
|
|
12
|
+
"""How the mercury process ended: its exit code or the signal that ended it, and everything it wrote to stderr."""
|
|
13
|
+
code: int | None
|
|
14
|
+
signal: str | None
|
|
15
|
+
stderr: str
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def _stderr_lines(exit: RunExit) -> list[str]:
|
|
19
|
+
return [line.strip() for line in exit.stderr.split('\n') if line.strip()]
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class MercuryError(Exception):
|
|
23
|
+
"""The base of every error the package raises; RPC errors carry the runner's code and data."""
|
|
24
|
+
def __init__(self, message: str, exit: RunExit | None = None, *, code: int | None = None, data: Any = None):
|
|
25
|
+
super().__init__(message)
|
|
26
|
+
self.exit = exit
|
|
27
|
+
self.code = code
|
|
28
|
+
self.data = data
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class MercuryRefusal(MercuryError):
|
|
32
|
+
"""Mercury refused the request: a refused outcome row (``outcome`` set) or an RPC refusal (``outcome`` is None)."""
|
|
33
|
+
def __init__(self, outcome: OutcomeRow | None, exit: RunExit | None = None, *, rpc: Mapping[str, Any] | None = None):
|
|
34
|
+
error: Mapping[str, Any] = rpc or (outcome.get('error', {}) if outcome is not None else {})
|
|
35
|
+
super().__init__(error.get('message', 'The request was refused'), exit, code=error.get('code'), data=error.get('data'))
|
|
36
|
+
self.outcome = outcome
|
|
37
|
+
self.error_class: ErrorClass | str = error.get('class', 'option')
|
|
38
|
+
self.detail: list[str] = list(error.get('detail', []))
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class MercuryUsageError(MercuryError):
|
|
42
|
+
"""The command line was refused (exit 2) before any row or answer; the message is the CLI's own first stderr line."""
|
|
43
|
+
def __init__(self, exit: RunExit, door: Door = 'run'):
|
|
44
|
+
lines = _stderr_lines(exit)
|
|
45
|
+
super().__init__(lines[0] if lines else f'mercury {door} refused the command line (exit 2) and wrote no reason', exit)
|
|
46
|
+
self.door = door
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class MercuryExitError(MercuryError):
|
|
50
|
+
"""The process ended before a run produced its outcome row or before a session was closed; the last stderr line is quoted."""
|
|
51
|
+
def __init__(self, exit: RunExit, door: Door = 'run', fallback: str | None = None):
|
|
52
|
+
why = f'ended by {exit.signal}' if exit.signal is not None else f'exited {exit.code if exit.code is not None else "without a code"}'
|
|
53
|
+
lines = _stderr_lines(exit)
|
|
54
|
+
reason = lines[-1] if lines else fallback
|
|
55
|
+
tail = f': {reason}' if reason else ''
|
|
56
|
+
super().__init__(f'mercury {door} {why} before {"an outcome row" if door == "run" else "the session was closed"}{tail}', exit)
|
|
57
|
+
self.door = door
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class MercurySpawnError(MercuryError):
|
|
61
|
+
"""The mercury process could not be started: no such executable, or no such working directory."""
|
|
62
|
+
def __init__(self, command: str, cause: Exception | str):
|
|
63
|
+
hint = ' (install Mercury CLI from https://mercury-cli.ai or pass the executable path in the mercury option)' if isinstance(cause, FileNotFoundError) else ''
|
|
64
|
+
super().__init__(f'could not start {command!r}: {cause}{hint}')
|
|
65
|
+
self.command = command
|
|
66
|
+
if isinstance(cause, Exception): self.__cause__ = cause
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class MercuryWireError(MercuryError):
|
|
70
|
+
"""A line on the wire was not a row or message the package knows; ``line``, ``reason`` and ``issues`` say what was wrong."""
|
|
71
|
+
def __init__(self, line: str, reason: str, row_type: str | None = None, issues: list[Issue] | None = None, exit: RunExit | None = None):
|
|
72
|
+
detail = '; '.join(f'{issue.path or "row"}: {issue.message}' for issue in (issues or [])[:3])
|
|
73
|
+
super().__init__(f'a stdout line is not a row or message the package knows ({reason}{f" {row_type}" if row_type else ""}){f": {detail}" if detail else ""}', exit)
|
|
74
|
+
self.line = line
|
|
75
|
+
self.reason = reason
|
|
76
|
+
self.row_type = row_type
|
|
77
|
+
self.issues: list[Issue] = issues or []
|