levier-runtime 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,289 @@
1
+ """Runtime configuration loading for the Levier Runtime SDK.
2
+
3
+ The public config is intentionally small: middleware connection, one runtime
4
+ identity, capacity, labels, and logging. Optional capabilities are configured
5
+ by the runtime implementation, not by the SDK.
6
+
7
+ Copyright 2026 The Levier Authors.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import os
13
+ from dataclasses import dataclass, field
14
+ from pathlib import Path
15
+ from typing import Any, Mapping
16
+
17
+ import yaml
18
+
19
+
20
+ class ConfigError(ValueError):
21
+ """Raised when a runtime configuration file is invalid."""
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class MiddlewareConfig:
26
+ """Levier RuntimeChannel connection settings."""
27
+
28
+ address: str
29
+ auth_token: str = field(default="", repr=False)
30
+ auth_token_file: str = ""
31
+ tls: bool = False
32
+
33
+
34
+ @dataclass(frozen=True)
35
+ class RuntimeConfig:
36
+ """Identity and capacity for one runtime process."""
37
+
38
+ runtime_name: str
39
+ instance_id: str
40
+ middleware: MiddlewareConfig
41
+ runtime_type: str = "normal"
42
+ max_concurrent_runs: int = 4
43
+ labels: Mapping[str, str] = field(default_factory=dict)
44
+ log_level: str = "info"
45
+
46
+
47
+ def load_runtime_config(
48
+ path: str | os.PathLike[str] | None = None,
49
+ *,
50
+ environ: Mapping[str, str] | None = None,
51
+ ) -> RuntimeConfig:
52
+ """Load `runtime.yaml`, then apply `LEVIER_RUNTIME_*` overrides.
53
+
54
+ A runtime can start with no YAML at all. In that case the SDK derives the
55
+ server address, runtime name, and local runtime credential from the user
56
+ profile written by ``levier up``/``levier init``.
57
+ """
58
+ env = os.environ if environ is None else environ
59
+ from .profile import default_runtime_config
60
+
61
+ configured = path or env.get("LEVIER_RUNTIME_CONFIG", "") or default_runtime_config()
62
+ data: dict[str, Any] = {}
63
+ label = "defaults"
64
+ use_profile_defaults = True
65
+ if configured and str(configured) != ".":
66
+ config_path = Path(configured)
67
+ label = str(config_path)
68
+ try:
69
+ raw = yaml.safe_load(config_path.read_text(encoding="utf-8"))
70
+ except OSError as exc:
71
+ raise ConfigError(f"read config {config_path}: {exc}") from exc
72
+ except yaml.YAMLError as exc:
73
+ raise ConfigError(f"parse config {config_path}: {exc}") from exc
74
+ if raw is None:
75
+ raw = {}
76
+ if not isinstance(raw, dict):
77
+ raise ConfigError(f"config {config_path} must be a mapping")
78
+ data = _deep_copy(raw)
79
+ # An empty placeholder file is the no-config case. A non-empty file is
80
+ # explicit and keeps strict field validation.
81
+ use_profile_defaults = not bool(data)
82
+
83
+ _apply_env(data, env)
84
+ if use_profile_defaults:
85
+ _apply_profile_defaults(data, env)
86
+ try:
87
+ return _parse_config(data, env, allow_local_defaults=use_profile_defaults)
88
+ except ConfigError as exc:
89
+ raise ConfigError(f"validate config {label}: {exc}") from exc
90
+
91
+
92
+ def _apply_profile_defaults(data: dict[str, Any], env: Mapping[str, str]) -> None:
93
+ from .profile import (
94
+ default_middleware_address,
95
+ default_runtime_name,
96
+ default_runtime_token,
97
+ )
98
+
99
+ middleware = data.get("middleware")
100
+ if not isinstance(middleware, dict):
101
+ middleware = {}
102
+ data["middleware"] = middleware
103
+ if not middleware.get("address") and not env.get("LEVIER_MIDDLEWARE_ADDRESS"):
104
+ address = default_middleware_address() or "127.0.0.1:9090"
105
+ middleware["address"] = address
106
+ if not middleware.get("auth_token") and not middleware.get("auth_token_file"):
107
+ token = env.get("LEVIER_RUNTIME_TOKEN") or default_runtime_token()
108
+ if token:
109
+ middleware["auth_token"] = token
110
+
111
+ runtime = data.get("runtime")
112
+ if not isinstance(runtime, dict):
113
+ runtime = {}
114
+ data["runtime"] = runtime
115
+ if not runtime.get("name"):
116
+ runtime["name"] = env.get("LEVIER_RUNTIME_NAME") or default_runtime_name() or "local"
117
+ if not runtime.get("instance_id"):
118
+ import socket
119
+
120
+ runtime["instance_id"] = f"{runtime['name']}-{socket.gethostname()}-{os.getpid()}"
121
+ if not runtime.get("type"):
122
+ runtime["type"] = "normal"
123
+ if not runtime.get("max_concurrent_runs"):
124
+ runtime["max_concurrent_runs"] = 4
125
+ if not data.get("logging"):
126
+ data["logging"] = {"level": "info"}
127
+
128
+
129
+ def _parse_config(
130
+ data: dict[str, Any],
131
+ env: Mapping[str, str],
132
+ *,
133
+ allow_local_defaults: bool = False,
134
+ ) -> RuntimeConfig:
135
+ middleware_data = _section(data, "middleware", required=True)
136
+ runtime_data = _section(data, "runtime", required=True)
137
+ address = _string(middleware_data, "middleware.address", "127.0.0.1:9090")
138
+ auth_token = _string(middleware_data, "middleware.auth_token", "")
139
+ auth_token_file = _string(middleware_data, "middleware.auth_token_file", "")
140
+ if not auth_token and auth_token_file:
141
+ auth_token = _read_secret_file(auth_token_file)
142
+ if not auth_token and allow_local_defaults and _is_local_address(address):
143
+ # The local Compose stack ships with this development credential.
144
+ auth_token = env.get("LEVIER_RUNTIME_TOKEN") or "change-me"
145
+ if not auth_token:
146
+ raise ConfigError(
147
+ "middleware.auth_token or middleware.auth_token_file is required "
148
+ "(or run `levier up`, which records the local runtime credential)"
149
+ )
150
+
151
+ runtime_name = _string(runtime_data, "runtime.name", "", required=True)
152
+ instance_id = _string(runtime_data, "runtime.instance_id", "", required=True)
153
+ runtime_type = _string(runtime_data, "runtime.type", "normal")
154
+ if runtime_type not in {"normal", "sandbox", "longterm"}:
155
+ raise ConfigError("runtime.type must be normal, sandbox, or longterm")
156
+ max_concurrent_runs = _positive_int(runtime_data, "runtime.max_concurrent_runs", 4)
157
+ labels = _string_map(runtime_data, "runtime.labels")
158
+ logging_data = _section(data, "logging", required=False)
159
+ log_level = _string(logging_data, "logging.level", "info")
160
+
161
+ tls = _boolean(middleware_data, "middleware.tls", False)
162
+ middleware = MiddlewareConfig(
163
+ address=address,
164
+ auth_token=auth_token,
165
+ auth_token_file=auth_token_file,
166
+ tls=tls,
167
+ )
168
+ return RuntimeConfig(
169
+ runtime_name=runtime_name,
170
+ instance_id=instance_id,
171
+ middleware=middleware,
172
+ runtime_type=runtime_type,
173
+ max_concurrent_runs=max_concurrent_runs,
174
+ labels=labels,
175
+ log_level=log_level,
176
+ )
177
+
178
+
179
+ def _apply_env(data: dict[str, Any], env: Mapping[str, str]) -> None:
180
+ _set(data, "middleware", "address", env.get("LEVIER_MIDDLEWARE_ADDRESS"))
181
+ _set(data, "middleware", "tls", env.get("LEVIER_MIDDLEWARE_TLS"))
182
+ _set(data, "middleware", "auth_token", env.get("LEVIER_RUNTIME_TOKEN"))
183
+ _set(data, "middleware", "auth_token_file", env.get("LEVIER_RUNTIME_TOKEN_FILE"))
184
+ _set(data, "runtime", "name", env.get("LEVIER_RUNTIME_NAME"))
185
+ _set(data, "runtime", "instance_id", env.get("LEVIER_RUNTIME_INSTANCE_ID"))
186
+ _set(data, "runtime", "type", env.get("LEVIER_RUNTIME_TYPE"))
187
+ _set(data, "runtime", "max_concurrent_runs", env.get("LEVIER_RUNTIME_MAX_CONCURRENT_RUNS"))
188
+ labels = env.get("LEVIER_RUNTIME_LABELS")
189
+ if labels is not None:
190
+ _section(data, "runtime", required=True)["labels"] = _parse_labels(labels)
191
+ _set(data, "logging", "level", env.get("LEVIER_RUNTIME_LOG_LEVEL"))
192
+
193
+
194
+ def _section(data: dict[str, Any], name: str, *, required: bool) -> dict[str, Any]:
195
+ value = data.get(name)
196
+ if value is None:
197
+ if required:
198
+ raise ConfigError(f"{name} is required")
199
+ return {}
200
+ if not isinstance(value, dict):
201
+ raise ConfigError(f"{name} must be a mapping")
202
+ return value
203
+
204
+
205
+ def _string(
206
+ section: dict[str, Any],
207
+ name: str,
208
+ default: str,
209
+ *,
210
+ required: bool = False,
211
+ ) -> str:
212
+ value = section.get(name.rsplit(".", 1)[-1], default)
213
+ if not isinstance(value, str):
214
+ raise ConfigError(f"{name} must be a string")
215
+ if required and not value:
216
+ raise ConfigError(f"{name} is required")
217
+ return value
218
+
219
+
220
+ def _positive_int(section: dict[str, Any], name: str, default: int) -> int:
221
+ value = section.get(name.rsplit(".", 1)[-1], default)
222
+ if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
223
+ raise ConfigError(f"{name} must be a positive integer")
224
+ return value
225
+
226
+
227
+ def _boolean(section: dict[str, Any], name: str, default: bool) -> bool:
228
+ value = section.get(name.rsplit(".", 1)[-1], default)
229
+ if isinstance(value, bool):
230
+ return value
231
+ if isinstance(value, str):
232
+ lowered = value.lower()
233
+ if lowered in {"true", "1", "yes"}:
234
+ return True
235
+ if lowered in {"false", "0", "no"}:
236
+ return False
237
+ raise ConfigError(f"{name} must be a boolean")
238
+
239
+
240
+ def _string_map(section: dict[str, Any], name: str) -> dict[str, str]:
241
+ value = section.get(name.rsplit(".", 1)[-1], {})
242
+ if not isinstance(value, dict):
243
+ raise ConfigError(f"{name} must be a mapping")
244
+ result: dict[str, str] = {}
245
+ for key, item in value.items():
246
+ if not isinstance(key, str) or not isinstance(item, str):
247
+ raise ConfigError(f"{name} keys and values must be strings")
248
+ result[key] = item
249
+ return result
250
+
251
+
252
+ def _is_local_address(address: str) -> bool:
253
+ host = address.strip()
254
+ if host.startswith("["):
255
+ host = host[1:].split("]", 1)[0]
256
+ elif ":" in host:
257
+ host = host.rsplit(":", 1)[0]
258
+ return host in {"127.0.0.1", "localhost", "::1", "0.0.0.0", ""}
259
+
260
+
261
+ def _read_secret_file(path: str) -> str:
262
+ try:
263
+ return Path(path).read_text(encoding="utf-8").strip()
264
+ except OSError as exc:
265
+ raise ConfigError(f"read secret file {path}: {exc}") from exc
266
+
267
+
268
+ def _parse_labels(value: str) -> dict[str, str]:
269
+ labels: dict[str, str] = {}
270
+ for item in value.split(","):
271
+ key, separator, label_value = item.partition("=")
272
+ if not separator or not key.strip():
273
+ raise ConfigError("LEVIER_RUNTIME_LABELS must use key=value,key=value")
274
+ labels[key.strip()] = label_value.strip()
275
+ return labels
276
+
277
+
278
+ def _set(data: dict[str, Any], section: str, key: str, value: str | None) -> None:
279
+ if value is None:
280
+ return
281
+ _section(data, section, required=True)[key] = value
282
+
283
+
284
+ def _deep_copy(value: Any) -> Any:
285
+ if isinstance(value, dict):
286
+ return {key: _deep_copy(item) for key, item in value.items()}
287
+ if isinstance(value, list):
288
+ return [_deep_copy(item) for item in value]
289
+ return value
@@ -0,0 +1,409 @@
1
+ """The single runtime-author-facing object.
2
+
3
+ `RunContext` deliberately exposes plain values and high-level methods only.
4
+ Transport details, protobuf messages, sequence numbers, and lease handling stay
5
+ inside the Runtime SDK.
6
+
7
+ The common loop is three calls: `await ctx.toolbox()` returns local and MCP
8
+ tools, `await ctx.chat(...)` calls the resolved model, and
9
+ `await ctx.invoke_all(reply, toolbox=tools)` dispatches every tool call.
10
+
11
+ Copyright 2026 The Levier Authors.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import asyncio
17
+ import json
18
+ import logging
19
+ import time
20
+ from datetime import datetime, timezone
21
+ from typing import Any, Mapping
22
+
23
+ from middleware.runtime.v1 import runtime_pb2
24
+
25
+ from .channel.client import ChannelClient
26
+ from .events import EventWriter
27
+ from .ids import new_ulid
28
+ from .types import (
29
+ McpBinding,
30
+ Message,
31
+ ModelConfig,
32
+ Timeouts,
33
+ ToolResult,
34
+ ToolSpec,
35
+ )
36
+
37
+
38
+ class RuntimeUsageError(ValueError):
39
+ """Raised when a runtime uses a context operation incorrectly."""
40
+
41
+
42
+ class RunContext:
43
+ """State and operations available to one `run(ctx)` invocation."""
44
+
45
+ def __init__(
46
+ self,
47
+ *,
48
+ runtime_name: str,
49
+ run_id: str,
50
+ app_id: str,
51
+ input_messages: list[Message],
52
+ params: dict[str, Any],
53
+ model: ModelConfig | None,
54
+ tools: list[ToolSpec],
55
+ mcp_bindings: list[McpBinding],
56
+ timeouts: Timeouts,
57
+ session_id: str | None,
58
+ resume_from: bytes | None,
59
+ trace_id: str,
60
+ channel: ChannelClient,
61
+ events: EventWriter,
62
+ attempt: int,
63
+ lease_epoch: int,
64
+ ) -> None:
65
+ self.runtime_name = runtime_name
66
+ self.run_id = run_id
67
+ self.app_id = app_id
68
+ self.input = input_messages
69
+ self.params = params
70
+ self.model = model
71
+ self.tools = tools
72
+ self.mcp_bindings = mcp_bindings
73
+ self.timeouts = timeouts
74
+ self.session_id = session_id
75
+ self.resume_from = resume_from
76
+ self.trace_id = trace_id
77
+ self.cancel_event = asyncio.Event()
78
+ self.started_at = datetime.now(tz=timezone.utc)
79
+ self.outcome = ""
80
+ self.task: asyncio.Task[Any] | None = None
81
+ # Useful for runtimes that include attempt information in their own
82
+ # checkpoint or logs; it is not a control-plane action.
83
+ self.attempt = attempt
84
+
85
+ self._channel = channel
86
+ self._events = events
87
+ self._attempt = attempt
88
+ self._lease_epoch = lease_epoch
89
+ self._toolbox = None
90
+ self.logger = logging.LoggerAdapter(
91
+ logging.getLogger("levier_runtime.run"),
92
+ {
93
+ "run_id": run_id,
94
+ "app_id": app_id,
95
+ "runtime_name": runtime_name,
96
+ "attempt": attempt,
97
+ "trace_id": trace_id,
98
+ },
99
+ )
100
+
101
+ @property
102
+ def cancelled(self) -> bool:
103
+ """Whether the control plane has requested cancellation."""
104
+ return self.cancel_event.is_set()
105
+
106
+ async def reply(self, text: str, *, role: str = "assistant") -> None:
107
+ """Emit one completed assistant message."""
108
+ await self.emit(
109
+ "MESSAGE_COMPLETED",
110
+ {
111
+ "message_id": new_ulid(),
112
+ "role": role,
113
+ "content": text,
114
+ },
115
+ )
116
+
117
+ async def emit(
118
+ self,
119
+ event_type: str,
120
+ data: dict[str, Any],
121
+ *,
122
+ ephemeral: bool = False,
123
+ ) -> None:
124
+ """Emit one event by protocol name, e.g. MESSAGE_DELTA.
125
+
126
+ The SDK assigns sequence numbers and envelope scope.
127
+ """
128
+ await self._events.emit(event_type, data, ephemeral=ephemeral)
129
+
130
+ async def toolbox(self) -> "Any":
131
+ """Return every local and MCP tool as one callable sequence.
132
+
133
+ MCP sessions are opened lazily on the first call and closed when the Run
134
+ ends. Runtime authors do not need to construct an MCP client.
135
+ """
136
+ if self._toolbox is None:
137
+ from .toolbox import Toolbox
138
+
139
+ self._toolbox = await Toolbox.open(self)
140
+ return self._toolbox
141
+
142
+ async def chat(
143
+ self,
144
+ messages: "list[Any] | None" = None,
145
+ *,
146
+ tools: "Any" = None,
147
+ on_delta: "Any" = None,
148
+ ) -> "Any":
149
+ """Call the model already resolved for this Run.
150
+
151
+ ``ctx.chat(ctx.input)`` uses every visible tool. The returned provider
152
+ response has ``content`` and ``tool_calls``. Provider failures become an
153
+ ERROR event and a failed Run automatically.
154
+ """
155
+ if self.model is None:
156
+ raise RuntimeUsageError("this run has no model; configure a provider and make it the default")
157
+ from .llm.base import Message as LLMMessage
158
+ from .llm.base import ModelConfig as LLMModelConfig
159
+ from .llm.router import ProviderRouter
160
+
161
+ values = list(self.input if messages is None else messages)
162
+ converted = []
163
+ for message in values:
164
+ if isinstance(message, LLMMessage):
165
+ converted.append(message)
166
+ elif isinstance(message, Mapping):
167
+ converted.append(
168
+ LLMMessage(
169
+ role=str(message.get("role", "user")),
170
+ content=str(message.get("content", "")),
171
+ name=str(message.get("name", "")),
172
+ tool_call_id=str(message.get("tool_call_id", "")),
173
+ )
174
+ )
175
+ else:
176
+ converted.append(
177
+ LLMMessage(
178
+ role=str(getattr(message, "role", "user")),
179
+ content=str(getattr(message, "content", "")),
180
+ name=str(getattr(message, "name", "")),
181
+ )
182
+ )
183
+
184
+ if tools is None:
185
+ tools = await self.toolbox()
186
+ specs = _tool_specs(tools)
187
+ model = LLMModelConfig(
188
+ provider=self.model.provider,
189
+ model=self.model.model,
190
+ api_key=self.model.api_key,
191
+ base_url=self.model.base_url,
192
+ params=dict(self.model.params),
193
+ )
194
+ return await ProviderRouter().complete(converted, specs, model, on_delta=on_delta)
195
+
196
+ async def invoke(
197
+ self,
198
+ call: "Any",
199
+ *,
200
+ toolbox: "Any" = None,
201
+ ) -> ToolResult:
202
+ """Parse one model tool call and execute it, local or MCP."""
203
+ name, arguments = _tool_call(call)
204
+ active = toolbox if toolbox is not None else await self.toolbox()
205
+ return await active.call(name, arguments)
206
+
207
+ async def invoke_all(
208
+ self,
209
+ response: "Any",
210
+ *,
211
+ toolbox: "Any" = None,
212
+ ) -> "list[ToolResult]":
213
+ """Execute every tool call in one provider response."""
214
+ calls = getattr(response, "tool_calls", response)
215
+ active = toolbox if toolbox is not None else await self.toolbox()
216
+ results: list[ToolResult] = []
217
+ for call in calls:
218
+ results.append(await self.invoke(call, toolbox=active))
219
+ return results
220
+
221
+ async def call_tool(
222
+ self,
223
+ name: str,
224
+ arguments: Mapping[str, Any] | str | None = None,
225
+ *,
226
+ timeout_ms: int | None = None,
227
+ emit_events: bool = True,
228
+ ) -> ToolResult:
229
+ """Call one tool through the middleware tool bridge.
230
+
231
+ By default the SDK emits TOOL_CALL_BEGIN/END and owns tool-call
232
+ observability. Runtimes that already emit those events can pass
233
+ ``emit_events=False`` to avoid duplicates.
234
+ """
235
+ if not name:
236
+ raise RuntimeUsageError("tool name is required")
237
+ if isinstance(arguments, Mapping):
238
+ arguments_json = json.dumps(
239
+ arguments,
240
+ ensure_ascii=False,
241
+ separators=(",", ":"),
242
+ )
243
+ elif arguments is None:
244
+ arguments_json = "{}"
245
+ elif isinstance(arguments, str):
246
+ arguments_json = arguments
247
+ else:
248
+ raise RuntimeUsageError("tool arguments must be a mapping or JSON string")
249
+
250
+ invocation_id = new_ulid()
251
+ if emit_events:
252
+ await self._emit_safe(
253
+ "TOOL_CALL_BEGIN",
254
+ {
255
+ "invocation_id": invocation_id,
256
+ "tool_name": name,
257
+ "arguments_json": arguments_json,
258
+ },
259
+ )
260
+
261
+ started = time.monotonic()
262
+ timeout = timeout_ms or self.timeouts.tool_ms or 60_000
263
+ try:
264
+ response = await self._channel.request(
265
+ runtime_pb2.ToolCallRequest(
266
+ invocation_id=invocation_id,
267
+ tool_name=name,
268
+ arguments_json=arguments_json,
269
+ timeout_ms=timeout,
270
+ ),
271
+ "tool_call_request",
272
+ run_id=self.run_id,
273
+ attempt=self._attempt,
274
+ lease_epoch=self._lease_epoch,
275
+ timeout=max(timeout / 1000.0 + 1.0, 1.0),
276
+ )
277
+ result = ToolResult.from_proto(response.tool_call_result)
278
+ except Exception as exc:
279
+ result = ToolResult(
280
+ ok=False,
281
+ error_code="TOOL_TRANSPORT_ERROR",
282
+ error_message=str(exc),
283
+ retryable=True,
284
+ )
285
+
286
+ if emit_events:
287
+ data: dict[str, Any] = {
288
+ "invocation_id": invocation_id,
289
+ "tool_name": name,
290
+ "ok": result.ok,
291
+ "duration_ms": int((time.monotonic() - started) * 1000),
292
+ }
293
+ if result.ok:
294
+ data["result_json"] = result.result_json
295
+ else:
296
+ data["error_code"] = result.error_code
297
+ data["error_message"] = result.error_message
298
+ data["retryable"] = result.retryable
299
+ await self._emit_safe("TOOL_CALL_END", data)
300
+ return result
301
+
302
+ async def error(
303
+ self,
304
+ code: str,
305
+ message: str,
306
+ *,
307
+ retryable: bool = False,
308
+ data: dict[str, Any] | None = None,
309
+ ) -> None:
310
+ """Emit one normalized ERROR event."""
311
+ payload: dict[str, Any] = {
312
+ "code": code,
313
+ "message": message,
314
+ "retryable": retryable,
315
+ }
316
+ if data:
317
+ payload.update(data)
318
+ await self.emit("ERROR", payload)
319
+
320
+ async def _emit_safe(self, event_type: str, data: dict[str, Any]) -> None:
321
+ """Emit an SDK observability event without failing the run itself."""
322
+ try:
323
+ await self.emit(event_type, data)
324
+ except Exception as exc: # noqa: BLE001 - observability must not mask run
325
+ self.logger.warning("runtime event emission failed", extra={
326
+ "event_type": event_type,
327
+ "error": str(exc),
328
+ })
329
+
330
+ async def checkpoint(self, state: bytes | Mapping[str, Any]) -> None:
331
+ """Send an opaque checkpoint for this session.
332
+
333
+ The SDK transports the bytes; the runtime owns their schema.
334
+ """
335
+ if not self.session_id:
336
+ raise RuntimeUsageError("checkpoint requires session_id")
337
+ if isinstance(state, Mapping):
338
+ data = json.dumps(
339
+ state,
340
+ ensure_ascii=False,
341
+ separators=(",", ":"),
342
+ ).encode("utf-8")
343
+ elif isinstance(state, (bytes, bytearray)):
344
+ data = bytes(state)
345
+ else:
346
+ raise RuntimeUsageError("checkpoint state must be bytes or a mapping")
347
+
348
+ watermark = await self._events.emit_checkpoint(
349
+ self.session_id,
350
+ data,
351
+ watermark=self._events.seq,
352
+ )
353
+ await self.emit(
354
+ "CHECKPOINT_SAVED",
355
+ {
356
+ "session_id": self.session_id,
357
+ "event_seq_watermark": watermark,
358
+ },
359
+ )
360
+
361
+ async def close_toolbox(self) -> None:
362
+ """Close any MCP sessions opened by :meth:`toolbox`."""
363
+ if self._toolbox is None:
364
+ return
365
+ await self._toolbox.close()
366
+ self._toolbox = None
367
+
368
+
369
+ def _tool_specs(tools: Any) -> list[Any]:
370
+ from .llm.base import ToolSpec as LLMToolSpec
371
+
372
+ if hasattr(tools, "specs") and callable(tools.specs):
373
+ return list(tools.specs())
374
+ result = []
375
+ for tool in tools:
376
+ if isinstance(tool, LLMToolSpec):
377
+ result.append(tool)
378
+ continue
379
+ schema = getattr(tool, "schema_json", "") or getattr(tool, "input_schema_json", "")
380
+ if not schema:
381
+ schema_value = getattr(tool, "schema", None)
382
+ if isinstance(schema_value, Mapping):
383
+ schema = json.dumps(schema_value, ensure_ascii=False, separators=(",", ":"))
384
+ result.append(
385
+ LLMToolSpec(
386
+ name=str(getattr(tool, "name", "")),
387
+ description=str(getattr(tool, "description", "")),
388
+ input_schema_json=str(schema or "{}"),
389
+ )
390
+ )
391
+ return result
392
+
393
+
394
+ def _tool_call(call: Any) -> tuple[str, str]:
395
+ if isinstance(call, Mapping):
396
+ name = str(call.get("name", ""))
397
+ arguments = call.get("arguments_json", call.get("arguments", "{}"))
398
+ else:
399
+ name = str(getattr(call, "name", ""))
400
+ arguments = getattr(call, "arguments_json", None)
401
+ if arguments is None:
402
+ arguments = getattr(call, "arguments", "{}")
403
+ if not name:
404
+ raise RuntimeUsageError("tool call has no name")
405
+ if isinstance(arguments, Mapping):
406
+ return name, json.dumps(arguments, ensure_ascii=False, separators=(",", ":"))
407
+ if arguments is None:
408
+ return name, "{}"
409
+ return name, str(arguments)