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.
@@ -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 []