统一:DSH 智能分析、Top100 与图表静默恢复
接入 DSH 专用运行时和对话界面,保留模型原始回答,支持会话分页、连续追问与显式报告。 补齐组合筛选、各维度 Top100、分组查询到排名图的转换,图表故障静默省略并基于保存数据自动恢复。 优化报告风格、图表顺序和表格换行,更新接入说明及构建输入。 验证:独立目录前后端构建通过;118 项 Java、102 项前端、102 项图表、14 项 DSH 应用和 13 项组合筛选检查通过。 仅提交相关源码、锁定依赖与测试;不包含凭据、会话、业务数据或本地产物。
This commit is contained in:
+21
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 DeepSeek
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -0,0 +1,28 @@
|
||||
from .api import DeepSeekHarness, DeepSeekHarnessConfig, RunResult, Session
|
||||
from .client import HarnessClient, HarnessConfig, UserQuestionHandler
|
||||
from .errors import SdkProtocolError
|
||||
from .models import (
|
||||
ApprovalRequestParams, ApprovalRequestResult, IncomingRequest, InitializeResponse,
|
||||
JsonObject, Notification, ServerInfo, UserQuestionAnswer, UserQuestionAnswerItem, UserQuestionRequest,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"DeepSeekHarness",
|
||||
"DeepSeekHarnessConfig",
|
||||
"Session",
|
||||
"RunResult",
|
||||
"HarnessClient",
|
||||
"HarnessConfig",
|
||||
"UserQuestionHandler",
|
||||
"UserQuestionRequest",
|
||||
"UserQuestionAnswer",
|
||||
"UserQuestionAnswerItem",
|
||||
"SdkProtocolError",
|
||||
"ApprovalRequestParams",
|
||||
"ApprovalRequestResult",
|
||||
"IncomingRequest",
|
||||
"InitializeResponse",
|
||||
"JsonObject",
|
||||
"Notification",
|
||||
"ServerInfo",
|
||||
]
|
||||
@@ -0,0 +1,335 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Callable, Literal
|
||||
|
||||
from .client import HarnessClient, HarnessConfig, UserQuestionHandler
|
||||
from .errors import SdkProtocolError
|
||||
from .models import CommandExecution, JsonObject, Notification
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class DeepSeekHarnessConfig:
|
||||
"""Configuration for launching the local DeepSeek Harness SDK runtime.
|
||||
|
||||
The runtime inherits the caller's environment by default, so existing
|
||||
DEEPSEEK_API_KEY and DEEPSEEK_BASE_URL settings keep working. Use ``env`` to
|
||||
intentionally override or inject variables for a subprocess.
|
||||
These values are startup input, not a live Session state mirror; Session
|
||||
commands do not rewrite this object.
|
||||
"""
|
||||
|
||||
provider: str = "deepseek-official"
|
||||
model: str = "deepseek-v4-flash"
|
||||
reasoning_effort: str | None = None
|
||||
max_tokens: int | None = None
|
||||
cwd: str | None = None
|
||||
runtime_cwd: str | None = None
|
||||
dsh_bin: str | None = None
|
||||
profile: str = "sdk"
|
||||
patches: tuple[str, ...] = ()
|
||||
dsh_home: str | None = None
|
||||
env: dict[str, str] = field(default_factory=dict)
|
||||
initialize_timeout_seconds: float = 30.0
|
||||
request_timeout_seconds: float | None = None
|
||||
shutdown_timeout_seconds: float | None = 1.0
|
||||
base_url: str | None = None
|
||||
api_key: str | None = None
|
||||
on_user_question: UserQuestionHandler | None = None
|
||||
approval_requests: bool = False
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RunResult:
|
||||
"""Completed input with result text, outcome, root events and Session-tree notifications."""
|
||||
|
||||
session_id: str
|
||||
final_response: str
|
||||
"""Final assistant text (empty when absent), native state-only result text, or a failure diagnostic."""
|
||||
finish_reason: str | None
|
||||
events: list[JsonObject]
|
||||
notifications: list[Notification]
|
||||
|
||||
|
||||
class _RunActivity:
|
||||
"""Collect one input's root events and Session-tree notifications from its admission."""
|
||||
|
||||
def __init__(self, session_id: str, receipt_kind: Literal["prompt", "command"], receipt_id: str) -> None:
|
||||
self.session_id = session_id
|
||||
self.receipt_kind = receipt_kind
|
||||
self.receipt_id = receipt_id
|
||||
self.received = False
|
||||
self.command_done = False
|
||||
self.events: list[JsonObject] = []
|
||||
self.notifications: list[Notification] = []
|
||||
|
||||
def record(self, notification: Notification, on_notification: Callable[[Notification], None] | None = None) -> bool:
|
||||
if notification.method == "session.query.completed":
|
||||
return False
|
||||
if not self.received:
|
||||
if self.receipt_kind == "prompt":
|
||||
if not _is_inbox_receipt(notification, self.session_id, self.receipt_id):
|
||||
return False
|
||||
elif not _is_command_event(notification, self.session_id, self.receipt_id, "command/run"):
|
||||
return False
|
||||
self.received = True
|
||||
event = notification.payload.get("event") if (
|
||||
notification.method == "session.event" and notification.payload.get("sessionId") == self.session_id
|
||||
) else None
|
||||
if (self.receipt_kind == "command" and isinstance(event, dict) and event.get("type") == "command/done"
|
||||
and isinstance(event.get("data"), dict) and event["data"].get("commandId") == self.receipt_id):
|
||||
self.command_done = True
|
||||
self.notifications.append(notification)
|
||||
if on_notification is not None:
|
||||
on_notification(notification)
|
||||
if isinstance(event, dict):
|
||||
self.events.append(event)
|
||||
return True
|
||||
|
||||
def result(self, completed: JsonObject | None = None) -> RunResult:
|
||||
if completed is not None and not self.command_done:
|
||||
raise SdkProtocolError("Command completion is missing matching lifecycle events")
|
||||
return RunResult(
|
||||
session_id=self.session_id,
|
||||
final_response=completed["finalResponse"] if completed is not None else final_response(self.events),
|
||||
finish_reason=completed["finishReason"] if completed is not None else finish_reason(self.events),
|
||||
events=self.events, notifications=self.notifications,
|
||||
)
|
||||
|
||||
|
||||
class DeepSeekHarness:
|
||||
"""Reusable synchronous SDK for running DeepSeek Harness agent turns.
|
||||
|
||||
The runtime subprocess starts lazily and remains owned by this instance
|
||||
across calls to :meth:`run`. Use the instance as a context manager, or call
|
||||
:meth:`close` explicitly when finished, so the subprocess is always reaped.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
config: DeepSeekHarnessConfig | None = None,
|
||||
*,
|
||||
_launch_args: tuple[str, ...] | None = None,
|
||||
**kwargs: object,
|
||||
) -> None:
|
||||
if config is not None and kwargs:
|
||||
raise TypeError("pass either DeepSeekHarnessConfig or keyword options, not both")
|
||||
self.config = config or DeepSeekHarnessConfig(**kwargs)
|
||||
cwd = str(Path(self.config.cwd or Path.cwd()).resolve())
|
||||
runtime_cwd = str(Path(self.config.runtime_cwd).resolve()) if self.config.runtime_cwd is not None else cwd
|
||||
self._cwd = cwd
|
||||
env = dict(self.config.env)
|
||||
if self.config.base_url is not None:
|
||||
env["DEEPSEEK_BASE_URL"] = self.config.base_url
|
||||
if self.config.api_key is not None:
|
||||
env["DEEPSEEK_API_KEY"] = self.config.api_key
|
||||
|
||||
self._client = HarnessClient(
|
||||
HarnessConfig(
|
||||
dsh_bin=self.config.dsh_bin,
|
||||
profile=self.config.profile,
|
||||
patches=self.config.patches,
|
||||
dsh_home=self.config.dsh_home,
|
||||
cwd=runtime_cwd,
|
||||
env=env,
|
||||
initialize_timeout_seconds=self.config.initialize_timeout_seconds,
|
||||
request_timeout_seconds=self.config.request_timeout_seconds,
|
||||
shutdown_timeout_seconds=self.config.shutdown_timeout_seconds,
|
||||
on_user_question=self.config.on_user_question,
|
||||
),
|
||||
_launch_args=_launch_args,
|
||||
)
|
||||
self._initialized = False
|
||||
|
||||
def __enter__(self) -> "DeepSeekHarness":
|
||||
self.start()
|
||||
return self
|
||||
|
||||
def __exit__(self, _exc_type, _exc, _tb) -> None:
|
||||
self.close()
|
||||
|
||||
@property
|
||||
def client(self) -> HarnessClient:
|
||||
return self._client
|
||||
|
||||
def start(self) -> None:
|
||||
if self._initialized:
|
||||
return
|
||||
self._client.start()
|
||||
self._client.initialize(
|
||||
cwd=self._cwd,
|
||||
provider=self.config.provider,
|
||||
model=self.config.model,
|
||||
reasoning_effort=self.config.reasoning_effort,
|
||||
max_tokens=self.config.max_tokens,
|
||||
approval_requests=self.config.approval_requests,
|
||||
)
|
||||
self._initialized = True
|
||||
|
||||
def close(self) -> None:
|
||||
self._client.close()
|
||||
self._initialized = False
|
||||
|
||||
def start_session(self, session_id: str | None = None) -> "Session":
|
||||
self.start()
|
||||
return Session(self, session_id or f"session-{uuid.uuid4().hex}")
|
||||
|
||||
def resume_session(self, session_id: str) -> "Session":
|
||||
"""Restore persisted history from the configured Harness home without sending input.
|
||||
|
||||
Missing, unreadable, incompatible, or occupied sessions raise instead of creating a new session.
|
||||
"""
|
||||
self.start()
|
||||
self._client.resume_session(session_id)
|
||||
return Session(self, session_id)
|
||||
|
||||
def run(
|
||||
self,
|
||||
input: str | list[JsonObject],
|
||||
*,
|
||||
session_id: str | None = None,
|
||||
on_notification: Callable[[Notification], None] | None = None,
|
||||
) -> RunResult:
|
||||
"""Run input to completion on a fresh or named Session and return its RunResult."""
|
||||
return self.start_session(session_id).run(input, on_notification=on_notification)
|
||||
|
||||
|
||||
class Session:
|
||||
def __init__(self, harness: DeepSeekHarness, session_id: str) -> None:
|
||||
self.harness = harness
|
||||
self.id = session_id
|
||||
|
||||
def get_working_directory(self) -> str:
|
||||
"""Read the effective directory, recovering a missing directory to the Session origin."""
|
||||
self.harness.start()
|
||||
return self.harness.client.get_working_directory(self.id)
|
||||
|
||||
def set_working_directory(self, path: str) -> str:
|
||||
"""Change the effective directory while existing processes retain their own directories."""
|
||||
self.harness.start()
|
||||
return self.harness.client.set_working_directory(self.id, path)
|
||||
|
||||
def run(
|
||||
self,
|
||||
input: str | list[JsonObject],
|
||||
*,
|
||||
on_notification: Callable[[Notification], None] | None = None,
|
||||
) -> RunResult:
|
||||
"""Run text or content blocks through native input routing.
|
||||
|
||||
Ordinary prompts finish at the next idle after their inbox receipt.
|
||||
State-only commands finish with their native outcome. Commands that
|
||||
submit model input wait for that activity; goal creation and resume wait
|
||||
through automatic rounds and the last reply after the goal stops.
|
||||
The first text block selects native commands. Matched commands require
|
||||
one text block with only encoded images beside it; native handlers decide
|
||||
which commands accept those images. Ordinary prompts retain block order
|
||||
and are queued through the existing prompt operation. Notifications retain
|
||||
wire order. Every result retains this Session id, its root events and
|
||||
Session-tree notifications, including overlapping work. Native refusals
|
||||
return finish_reason="error". Routing, transport and observer failures
|
||||
raise without rolling back work.
|
||||
"""
|
||||
self.harness.start()
|
||||
with self.harness.client.subscribe_session_notifications(self.id) as subscription:
|
||||
response = self.harness.client._query(self.id, input)
|
||||
if isinstance(response, CommandExecution):
|
||||
activity = _RunActivity(self.id, "command", response.command_id)
|
||||
while True:
|
||||
notification = subscription.next()
|
||||
payload = notification.payload
|
||||
if notification.method == "session.query.completed" and payload.get("sessionId") == self.id:
|
||||
if not isinstance(payload.get("commandId"), str) or not payload["commandId"]:
|
||||
raise SdkProtocolError("Invalid session.query.completed command identity")
|
||||
if payload["commandId"] != response.command_id:
|
||||
continue
|
||||
if (not isinstance(payload.get("finalResponse"), str)
|
||||
or not isinstance(payload.get("finishReason"), str) or not payload["finishReason"]):
|
||||
raise SdkProtocolError("Invalid session.query.completed result")
|
||||
# Failure completion can precede handler settlement; its lifecycle precedes the RPC response.
|
||||
while not activity.command_done:
|
||||
try:
|
||||
queued = subscription.next(timeout_seconds=0)
|
||||
except TimeoutError:
|
||||
break
|
||||
activity.record(queued, on_notification)
|
||||
return activity.result(payload)
|
||||
activity.record(notification, on_notification)
|
||||
activity = _RunActivity(self.id, "prompt", response)
|
||||
while True:
|
||||
notification = subscription.next()
|
||||
if not activity.record(notification, on_notification):
|
||||
continue
|
||||
if (
|
||||
notification.method == "session.status"
|
||||
and notification.payload.get("sessionId") == self.id
|
||||
and notification.payload.get("status") == "idle"
|
||||
):
|
||||
break
|
||||
|
||||
return activity.result()
|
||||
|
||||
|
||||
def _is_inbox_receipt(notification: Notification, session_id: str, message_id: str) -> bool:
|
||||
if notification.method != "session.event" or notification.payload.get("sessionId") != session_id:
|
||||
return False
|
||||
event = notification.payload.get("event")
|
||||
if not isinstance(event, dict) or event.get("type") != "agent/inbox/spliced":
|
||||
return False
|
||||
data = event.get("data")
|
||||
inserted = data.get("inserted") if isinstance(data, dict) else None
|
||||
return isinstance(inserted, list) and any(
|
||||
isinstance(message, dict) and message.get("id") == message_id for message in inserted
|
||||
)
|
||||
|
||||
|
||||
def _is_command_event(notification: Notification, session_id: str, command_id: str, event_type: str) -> bool:
|
||||
if notification.method != "session.event" or notification.payload.get("sessionId") != session_id:
|
||||
return False
|
||||
event = notification.payload.get("event")
|
||||
if not isinstance(event, dict) or event.get("type") != event_type:
|
||||
return False
|
||||
data = event.get("data")
|
||||
return isinstance(data, dict) and data.get("commandId") == command_id
|
||||
|
||||
|
||||
def final_response(events: list[JsonObject]) -> str:
|
||||
for event in reversed(events):
|
||||
if event.get("type") != "assistant/message":
|
||||
continue
|
||||
data = event.get("data")
|
||||
if not isinstance(data, dict):
|
||||
continue
|
||||
message = data.get("message")
|
||||
content_owner = message if isinstance(message, dict) else data
|
||||
content = content_owner.get("content")
|
||||
if not isinstance(content, list):
|
||||
continue
|
||||
parts: list[str] = []
|
||||
for block in content:
|
||||
if isinstance(block, dict) and block.get("type") == "text":
|
||||
parts.append(str(block.get("text") or ""))
|
||||
return "".join(parts)
|
||||
return ""
|
||||
|
||||
|
||||
def finish_reason(events: list[JsonObject]) -> str | None:
|
||||
"""Return the last turn-ending kind.
|
||||
|
||||
The input must contain root-session events from one owned run interval.
|
||||
|
||||
Raises:
|
||||
SdkProtocolError: The last ``turn/end`` has no string reason kind.
|
||||
"""
|
||||
for event in reversed(events):
|
||||
if event.get("type") != "turn/end":
|
||||
continue
|
||||
data = event.get("data")
|
||||
reason = data.get("reason") if isinstance(data, dict) else None
|
||||
kind = reason.get("kind") if isinstance(reason, dict) else None
|
||||
if not isinstance(kind, str):
|
||||
raise SdkProtocolError("turn/end event requires a string data.reason.kind")
|
||||
return kind
|
||||
return None
|
||||
@@ -0,0 +1,735 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import queue
|
||||
import subprocess
|
||||
import threading
|
||||
import time
|
||||
import uuid
|
||||
from collections import deque
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Callable, TypeAlias, TypeVar
|
||||
|
||||
from pydantic import BaseModel, ValidationError
|
||||
|
||||
from .errors import JsonRpcError, SdkProtocolError, TransportClosedError
|
||||
from .models import CommandExecution, IncomingRequest, InitializeResponse, JsonObject, JsonValue, Notification, UserQuestionAnswer, UserQuestionRequest
|
||||
|
||||
ModelT = TypeVar("ModelT", bound=BaseModel)
|
||||
NotificationFilter: TypeAlias = Callable[[Notification], bool]
|
||||
UserQuestionHandler: TypeAlias = Callable[[UserQuestionRequest, threading.Event], UserQuestionAnswer | JsonObject]
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class HarnessConfig:
|
||||
"""Configuration for launching the local DeepSeek Harness SDK runtime."""
|
||||
|
||||
dsh_bin: str | None = None
|
||||
profile: str = "sdk"
|
||||
patches: tuple[str, ...] = ()
|
||||
dsh_home: str | None = None
|
||||
cwd: str | None = None
|
||||
env: dict[str, str] | None = None
|
||||
initialize_timeout_seconds: float = 30.0
|
||||
request_timeout_seconds: float | None = None
|
||||
shutdown_timeout_seconds: float | None = 1.0
|
||||
# Callbacks run outside the reader; observe the Event to release work on cancellation.
|
||||
on_user_question: UserQuestionHandler | None = None
|
||||
|
||||
|
||||
class HarnessClient:
|
||||
"""Synchronous JSON-RPC client for the DeepSeek Harness SDK runtime over stdio."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
config: HarnessConfig | None = None,
|
||||
*,
|
||||
_launch_args: tuple[str, ...] | None = None,
|
||||
) -> None:
|
||||
self.config = config or HarnessConfig()
|
||||
self._launch_args = _launch_args
|
||||
self._proc: subprocess.Popen[str] | None = None
|
||||
self._lock = threading.Lock()
|
||||
self._write_lock = threading.Lock()
|
||||
self._responses: dict[str, queue.Queue[JsonValue | BaseException]] = {}
|
||||
self._notifications: queue.Queue[Notification | BaseException] = queue.Queue()
|
||||
self._notification_subscribers: dict[
|
||||
str, tuple[queue.Queue[Notification | BaseException], NotificationFilter | None]
|
||||
] = {}
|
||||
self._session_parents: dict[str, str] = {}
|
||||
self._requests: queue.Queue[IncomingRequest | BaseException] = queue.Queue()
|
||||
self._stderr_lines: deque[str] = deque(maxlen=400)
|
||||
self._reader_thread: threading.Thread | None = None
|
||||
self._stderr_thread: threading.Thread | None = None
|
||||
self._question_tasks: dict[str, tuple[threading.Event, threading.Thread]] = {}
|
||||
self._closing = False
|
||||
self._user_question_handler: UserQuestionHandler | None = None
|
||||
|
||||
def __enter__(self) -> "HarnessClient":
|
||||
self.start()
|
||||
return self
|
||||
|
||||
def __exit__(self, _exc_type, _exc, _tb) -> None:
|
||||
self.close()
|
||||
|
||||
def start(self) -> None:
|
||||
if self._proc is not None:
|
||||
return
|
||||
with self._lock:
|
||||
self._session_parents.clear()
|
||||
self._question_tasks.clear()
|
||||
self._closing = False
|
||||
self._user_question_handler = self.config.on_user_question
|
||||
env = os.environ.copy()
|
||||
if self.config.env:
|
||||
env.update(self.config.env)
|
||||
args = list(self._launch_args or self._default_launch_args(env))
|
||||
self._proc = subprocess.Popen(
|
||||
args,
|
||||
stdin=subprocess.PIPE,
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.PIPE,
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
cwd=None if self.config.cwd is None else str(Path(self.config.cwd).resolve()),
|
||||
env=env,
|
||||
bufsize=1,
|
||||
)
|
||||
self._start_reader_thread()
|
||||
self._start_stderr_thread()
|
||||
|
||||
def close(self) -> None:
|
||||
"""Close the runtime after a bounded opportunity to flush durable state."""
|
||||
with self._lock:
|
||||
self._closing = True
|
||||
question_tasks = list(self._question_tasks.values())
|
||||
for cancelled, _thread in question_tasks:
|
||||
cancelled.set()
|
||||
proc = self._proc
|
||||
if proc is None:
|
||||
return
|
||||
shutdown_completed = False
|
||||
try:
|
||||
self.request("shutdown", None, response_model=_EmptyResponse, timeout_seconds=self.config.shutdown_timeout_seconds)
|
||||
shutdown_completed = True
|
||||
except Exception as exc:
|
||||
self._stderr_lines.append(f"shutdown request failed: {exc}")
|
||||
if proc.stdin:
|
||||
try:
|
||||
proc.stdin.close()
|
||||
except Exception as exc:
|
||||
self._stderr_lines.append(f"stdin close failed: {exc}")
|
||||
if shutdown_completed:
|
||||
try:
|
||||
proc.wait(timeout=self.config.shutdown_timeout_seconds)
|
||||
except subprocess.TimeoutExpired:
|
||||
pass
|
||||
if proc.poll() is None:
|
||||
try:
|
||||
proc.terminate()
|
||||
except ProcessLookupError:
|
||||
pass
|
||||
if proc.poll() is None:
|
||||
try:
|
||||
proc.wait(timeout=self.config.shutdown_timeout_seconds)
|
||||
except subprocess.TimeoutExpired:
|
||||
proc.kill()
|
||||
proc.wait()
|
||||
self._proc = None
|
||||
self._fail_waiters(self._runtime_closed_error("DeepSeek Harness runtime closed"))
|
||||
if self._reader_thread and self._reader_thread.is_alive():
|
||||
self._reader_thread.join(timeout=0.5)
|
||||
if self._stderr_thread and self._stderr_thread.is_alive():
|
||||
self._stderr_thread.join(timeout=0.5)
|
||||
deadline = time.monotonic() + 0.5
|
||||
for _cancelled, thread in question_tasks:
|
||||
if thread is not threading.current_thread():
|
||||
thread.join(timeout=max(0, deadline - time.monotonic()))
|
||||
|
||||
def initialize(
|
||||
self,
|
||||
*,
|
||||
cwd: str,
|
||||
provider: str,
|
||||
model: str,
|
||||
reasoning_effort: str | None = None,
|
||||
max_tokens: int | None = None,
|
||||
approval_requests: bool = False,
|
||||
) -> InitializeResponse:
|
||||
"""Initialize the runtime; approval_requests enables approval/request reception.
|
||||
|
||||
When enabled, drain next_request() concurrently with blocking waits and
|
||||
return one-operation decisions through respond(). Omission preserves the
|
||||
runtime's composed approval answerers.
|
||||
"""
|
||||
payload: JsonObject = {
|
||||
"cwd": str(Path(cwd).resolve()),
|
||||
"provider": provider,
|
||||
"model": model,
|
||||
}
|
||||
if approval_requests:
|
||||
payload["approvalRequests"] = True
|
||||
if reasoning_effort is not None:
|
||||
payload["reasoningEffort"] = reasoning_effort
|
||||
if max_tokens is not None:
|
||||
payload["maxTokens"] = max_tokens
|
||||
if self._user_question_handler is not None:
|
||||
payload["capabilities"] = {"userQuestions": True}
|
||||
try:
|
||||
return self.request(
|
||||
"initialize",
|
||||
payload,
|
||||
response_model=InitializeResponse,
|
||||
timeout_seconds=self.config.initialize_timeout_seconds,
|
||||
)
|
||||
except TimeoutError as error:
|
||||
self.close()
|
||||
raise TimeoutError(f"{error}\nselected dsh profile {self.config.profile!r}") from error
|
||||
except BaseException as error:
|
||||
self.close()
|
||||
diagnostics = self._runtime_diagnostics()
|
||||
if isinstance(error, JsonRpcError) and diagnostics:
|
||||
raise JsonRpcError(
|
||||
error.code,
|
||||
f"{error.message}\n{diagnostics}",
|
||||
error.data,
|
||||
) from error
|
||||
raise
|
||||
|
||||
def session_prompt(
|
||||
self,
|
||||
session_id: str,
|
||||
content_blocks: list[JsonObject],
|
||||
*,
|
||||
on_notification: Callable[[Notification], None] | None = None,
|
||||
notification_subscription: "NotificationSubscription | None" = None,
|
||||
) -> str:
|
||||
payload: JsonObject = {"sessionId": session_id, "contentBlocks": content_blocks}
|
||||
response = self.request(
|
||||
"session/prompt",
|
||||
payload,
|
||||
response_model=_SessionPromptResponse,
|
||||
on_notification=on_notification,
|
||||
notification_filter=self._notification_belongs_to_session_tree(session_id),
|
||||
notification_subscription=notification_subscription,
|
||||
)
|
||||
return response.messageId
|
||||
|
||||
def resume_session(self, session_id: str) -> None:
|
||||
"""Restore a persisted session without sending a prompt; propagate restoration failures."""
|
||||
self.request(
|
||||
"session/resume",
|
||||
{"sessionId": session_id},
|
||||
response_model=_EmptyResponse,
|
||||
)
|
||||
|
||||
def _query(
|
||||
self, session_id: str, input: str | list[JsonObject],
|
||||
) -> str | CommandExecution:
|
||||
"""Return a validated prompt receipt or command result for high-level run callers."""
|
||||
blocks = [{"type": "text", "text": input}] if isinstance(input, str) else input
|
||||
result = self._request_raw("session/query", {
|
||||
"sessionId": session_id, "contentBlocks": blocks,
|
||||
})
|
||||
if isinstance(result, dict):
|
||||
if result.get("kind") == "prompt" and isinstance(result.get("messageId"), str) and result["messageId"]:
|
||||
return result["messageId"]
|
||||
if result.get("kind") == "command":
|
||||
return _command_execution(result.get("execution"))
|
||||
raise SdkProtocolError("session/query requires a prompt messageId or command execution result")
|
||||
|
||||
def get_working_directory(self, session_id: str) -> str:
|
||||
"""Read the effective directory, recovering a missing directory to the Session origin."""
|
||||
response = self.request(
|
||||
"session/working-directory/get",
|
||||
{"sessionId": session_id},
|
||||
response_model=_WorkingDirectoryResponse,
|
||||
)
|
||||
return response.cwd
|
||||
|
||||
def set_working_directory(self, session_id: str, path: str) -> str:
|
||||
"""Enter an absolute or Session-relative directory without changing origin or permissions."""
|
||||
response = self.request(
|
||||
"session/working-directory/set",
|
||||
{"sessionId": session_id, "path": path},
|
||||
response_model=_WorkingDirectoryResponse,
|
||||
)
|
||||
return response.cwd
|
||||
|
||||
def request(
|
||||
self,
|
||||
method: str,
|
||||
params: JsonObject | None,
|
||||
*,
|
||||
response_model: type[ModelT],
|
||||
timeout_seconds: float | None = None,
|
||||
on_notification: Callable[[Notification], None] | None = None,
|
||||
notification_filter: NotificationFilter | None = None,
|
||||
notification_subscription: "NotificationSubscription | None" = None,
|
||||
) -> ModelT:
|
||||
result = self._request_raw(
|
||||
method,
|
||||
params,
|
||||
timeout_seconds=timeout_seconds,
|
||||
on_notification=on_notification,
|
||||
notification_filter=notification_filter,
|
||||
notification_subscription=notification_subscription,
|
||||
)
|
||||
if not isinstance(result, dict):
|
||||
raise TypeError(f"{method} response must be a JSON object")
|
||||
return response_model.model_validate(result)
|
||||
|
||||
def notify(self, method: str, params: JsonObject | None = None) -> None:
|
||||
message: JsonObject = {"jsonrpc": "2.0", "method": method}
|
||||
if params is not None:
|
||||
message["params"] = params
|
||||
self._write_message(message)
|
||||
|
||||
def next_notification(self) -> Notification:
|
||||
item = self._notifications.get()
|
||||
if isinstance(item, BaseException):
|
||||
raise item
|
||||
return item
|
||||
|
||||
def subscribe_notifications(
|
||||
self,
|
||||
notification_filter: NotificationFilter | None = None,
|
||||
) -> "NotificationSubscription":
|
||||
subscription_id = str(uuid.uuid4())
|
||||
notifications: queue.Queue[Notification | BaseException] = queue.Queue()
|
||||
with self._lock:
|
||||
self._notification_subscribers[subscription_id] = (notifications, notification_filter)
|
||||
return NotificationSubscription(self, subscription_id, notifications)
|
||||
|
||||
def subscribe_session_notifications(self, session_id: str) -> "NotificationSubscription":
|
||||
"""Subscribe to a session and descendants discovered from subagent lifecycle edges."""
|
||||
return self.subscribe_notifications(self._notification_belongs_to_session_tree(session_id))
|
||||
|
||||
def next_request(self) -> IncomingRequest:
|
||||
item = self._requests.get()
|
||||
if isinstance(item, BaseException):
|
||||
raise item
|
||||
return item
|
||||
|
||||
def respond(self, request_id: str | int, result: JsonValue) -> None:
|
||||
self._write_message({"jsonrpc": "2.0", "id": request_id, "result": result})
|
||||
|
||||
def respond_error(
|
||||
self,
|
||||
request_id: str | int,
|
||||
*,
|
||||
code: int,
|
||||
message: str,
|
||||
data: JsonValue | None = None,
|
||||
) -> None:
|
||||
error: JsonObject = {"code": code, "message": message}
|
||||
if data is not None:
|
||||
error["data"] = data
|
||||
self._write_message({"jsonrpc": "2.0", "id": request_id, "error": error})
|
||||
|
||||
def _request_raw(
|
||||
self,
|
||||
method: str,
|
||||
params: JsonObject | None = None,
|
||||
*,
|
||||
timeout_seconds: float | None = None,
|
||||
on_notification: Callable[[Notification], None] | None = None,
|
||||
notification_filter: NotificationFilter | None = None,
|
||||
notification_subscription: "NotificationSubscription | None" = None,
|
||||
) -> JsonValue:
|
||||
request_id = str(uuid.uuid4())
|
||||
waiter: queue.Queue[JsonValue | BaseException] = queue.Queue(maxsize=1)
|
||||
temp_subscription: NotificationSubscription | None = None
|
||||
subscription = notification_subscription
|
||||
with self._lock:
|
||||
self._responses[request_id] = waiter
|
||||
if on_notification is not None and subscription is None:
|
||||
temp_subscription = self.subscribe_notifications(notification_filter)
|
||||
subscription = temp_subscription
|
||||
try:
|
||||
message: JsonObject = {"jsonrpc": "2.0", "id": request_id, "method": method}
|
||||
if params is not None:
|
||||
message["params"] = params
|
||||
self._write_message(message)
|
||||
except BaseException:
|
||||
with self._lock:
|
||||
self._responses.pop(request_id, None)
|
||||
if temp_subscription is not None:
|
||||
temp_subscription.close()
|
||||
raise
|
||||
timeout = self.config.request_timeout_seconds if timeout_seconds is None else timeout_seconds
|
||||
deadline = None if timeout is None else time.monotonic() + timeout
|
||||
try:
|
||||
while True:
|
||||
if on_notification is not None and subscription is not None:
|
||||
subscription.drain(on_notification)
|
||||
wait_timeout = None
|
||||
if on_notification is not None:
|
||||
wait_timeout = 0.05
|
||||
if deadline is not None:
|
||||
remaining = deadline - time.monotonic()
|
||||
if remaining <= 0:
|
||||
with self._lock:
|
||||
self._responses.pop(request_id, None)
|
||||
diagnostics = self._runtime_diagnostics()
|
||||
suffix = f"\n{diagnostics}" if diagnostics else ""
|
||||
raise TimeoutError(
|
||||
f"{method} timed out waiting for DeepSeek Harness runtime{suffix}"
|
||||
)
|
||||
wait_timeout = remaining if wait_timeout is None else min(wait_timeout, remaining)
|
||||
try:
|
||||
item = waiter.get(timeout=wait_timeout)
|
||||
if on_notification is not None and subscription is not None:
|
||||
subscription.drain(on_notification)
|
||||
break
|
||||
except queue.Empty:
|
||||
continue
|
||||
except BaseException:
|
||||
with self._lock:
|
||||
self._responses.pop(request_id, None)
|
||||
if temp_subscription is not None:
|
||||
temp_subscription.close()
|
||||
raise
|
||||
finally:
|
||||
if temp_subscription is not None:
|
||||
temp_subscription.close()
|
||||
if isinstance(item, BaseException):
|
||||
raise item
|
||||
return item
|
||||
|
||||
def _write_message(self, message: JsonObject) -> None:
|
||||
proc = self._proc
|
||||
if proc is None or proc.stdin is None:
|
||||
raise TransportClosedError("DeepSeek Harness runtime is not running")
|
||||
try:
|
||||
payload = json.dumps(message, separators=(",", ":")) + "\n"
|
||||
with self._write_lock:
|
||||
proc.stdin.write(payload)
|
||||
proc.stdin.flush()
|
||||
except Exception as exc:
|
||||
raise self._runtime_closed_error("Failed to write to DeepSeek Harness runtime") from exc
|
||||
|
||||
def _start_reader_thread(self) -> None:
|
||||
self._reader_thread = threading.Thread(target=self._reader_loop, name="dsh-runtime-reader", daemon=True)
|
||||
self._reader_thread.start()
|
||||
|
||||
def _start_stderr_thread(self) -> None:
|
||||
self._stderr_thread = threading.Thread(target=self._stderr_loop, name="dsh-runtime-stderr", daemon=True)
|
||||
self._stderr_thread.start()
|
||||
|
||||
def _reader_loop(self) -> None:
|
||||
proc = self._proc
|
||||
if proc is None or proc.stdout is None:
|
||||
return
|
||||
try:
|
||||
for line in proc.stdout:
|
||||
if not line.strip():
|
||||
continue
|
||||
try:
|
||||
message = json.loads(line)
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
self._handle_message(message)
|
||||
except BaseException as exc:
|
||||
self._fail_waiters(exc)
|
||||
finally:
|
||||
self._fail_waiters(self._runtime_closed_error("DeepSeek Harness runtime stdout closed"))
|
||||
|
||||
def _stderr_loop(self) -> None:
|
||||
proc = self._proc
|
||||
if proc is None or proc.stderr is None:
|
||||
return
|
||||
for line in proc.stderr:
|
||||
self._stderr_lines.append(line.rstrip())
|
||||
|
||||
def _handle_message(self, message: object) -> None:
|
||||
if not isinstance(message, dict):
|
||||
return
|
||||
msg_id = message.get("id")
|
||||
method = message.get("method")
|
||||
if isinstance(msg_id, (str, int)) and isinstance(method, str):
|
||||
params = message.get("params")
|
||||
request = IncomingRequest(id=msg_id, method=method, payload=params if isinstance(params, dict) else {})
|
||||
if method == "user-question/ask" and self._user_question_handler is not None:
|
||||
self._start_user_question(request)
|
||||
else:
|
||||
self._requests.put(request)
|
||||
return
|
||||
if isinstance(msg_id, (str, int)):
|
||||
with self._lock:
|
||||
waiter = self._responses.pop(str(msg_id), None)
|
||||
if waiter is None:
|
||||
return
|
||||
if isinstance(message.get("error"), dict):
|
||||
err = message["error"]
|
||||
waiter.put(JsonRpcError(_int_or_none(err.get("code")), str(err.get("message", "JSON-RPC error")), err.get("data")))
|
||||
else:
|
||||
waiter.put(message.get("result"))
|
||||
return
|
||||
if isinstance(method, str):
|
||||
params = message.get("params")
|
||||
notification = Notification(method=method, payload=params if isinstance(params, dict) else {})
|
||||
with self._lock:
|
||||
if method == "user-question.cancelled":
|
||||
task = self._question_tasks.get(str(notification.payload.get("requestId")))
|
||||
if task is not None:
|
||||
task[0].set()
|
||||
self._record_session_relationship_locked(notification)
|
||||
subscribers = list(self._notification_subscribers.items())
|
||||
delivered = False
|
||||
for subscription_id, (subscriber, predicate) in subscribers:
|
||||
try:
|
||||
matches = predicate is None or predicate(notification)
|
||||
except BaseException as exc:
|
||||
with self._lock:
|
||||
current = self._notification_subscribers.get(subscription_id)
|
||||
if current is not None and current[0] is subscriber:
|
||||
self._notification_subscribers.pop(subscription_id, None)
|
||||
subscriber.put(exc)
|
||||
continue
|
||||
if matches:
|
||||
subscriber.put(notification)
|
||||
delivered = True
|
||||
if not delivered:
|
||||
self._notifications.put(notification)
|
||||
|
||||
def _fail_waiters(self, exc: BaseException) -> None:
|
||||
with self._lock:
|
||||
for cancelled, _thread in self._question_tasks.values():
|
||||
cancelled.set()
|
||||
waiters = list(self._responses.values())
|
||||
self._responses.clear()
|
||||
subscribers = list(self._notification_subscribers.values())
|
||||
self._notification_subscribers.clear()
|
||||
for waiter in waiters:
|
||||
waiter.put(exc)
|
||||
for subscriber, _predicate in subscribers:
|
||||
subscriber.put(exc)
|
||||
self._notifications.put(exc)
|
||||
self._requests.put(exc)
|
||||
|
||||
def _start_user_question(self, incoming: IncomingRequest) -> None:
|
||||
"""Keep the reader free to receive cancellation, other responses, and shutdown."""
|
||||
handler = self._user_question_handler
|
||||
proc = self._proc
|
||||
try:
|
||||
request = UserQuestionRequest.model_validate(incoming.payload)
|
||||
if any(not isinstance(item.get("id"), str) or not isinstance(item.get("question"), str) for item in request.questions):
|
||||
raise ValueError("questions require id and question strings")
|
||||
except ValueError:
|
||||
self.respond_error(incoming.id, code=-32602, message="invalid user-question/ask parameters")
|
||||
return
|
||||
cancelled = threading.Event()
|
||||
|
||||
def answer() -> None:
|
||||
try:
|
||||
if cancelled.is_set() or handler is None:
|
||||
return
|
||||
result = handler(request, cancelled)
|
||||
wire_result = result.model_dump(exclude_none=True) if isinstance(result, UserQuestionAnswer) else result
|
||||
with self._lock:
|
||||
if not cancelled.is_set() and self._proc is proc:
|
||||
self.respond(incoming.id, wire_result)
|
||||
except Exception as exc:
|
||||
with self._lock:
|
||||
if not cancelled.is_set() and self._proc is proc:
|
||||
try:
|
||||
self.respond_error(incoming.id, code=-32603, message=str(exc))
|
||||
except TransportClosedError:
|
||||
cancelled.set()
|
||||
finally:
|
||||
with self._lock:
|
||||
current = self._question_tasks.get(request.request_id)
|
||||
if current is not None and current[0] is cancelled:
|
||||
self._question_tasks.pop(request.request_id, None)
|
||||
|
||||
thread = threading.Thread(target=answer, name="dsh-user-question", daemon=True)
|
||||
with self._lock:
|
||||
if self._closing:
|
||||
return
|
||||
if request.request_id in self._question_tasks:
|
||||
self.respond_error(incoming.id, code=-32602, message="duplicate user-question requestId")
|
||||
return
|
||||
self._question_tasks[request.request_id] = (cancelled, thread)
|
||||
try:
|
||||
thread.start()
|
||||
except BaseException:
|
||||
self._question_tasks.pop(request.request_id, None)
|
||||
cancelled.set()
|
||||
raise
|
||||
|
||||
def _runtime_closed_error(self, reason: str) -> TransportClosedError:
|
||||
diagnostics = self._runtime_diagnostics()
|
||||
return TransportClosedError(f"{reason}\n{diagnostics}" if diagnostics else reason)
|
||||
|
||||
def _runtime_diagnostics(self) -> str:
|
||||
"""Return available subprocess state for transport failures and timeouts."""
|
||||
proc = self._proc
|
||||
if (
|
||||
proc is not None
|
||||
and proc.poll() is not None
|
||||
and self._stderr_thread is not None
|
||||
and self._stderr_thread.is_alive()
|
||||
and threading.current_thread() is not self._stderr_thread
|
||||
):
|
||||
self._stderr_thread.join(timeout=0.1)
|
||||
|
||||
parts: list[str] = []
|
||||
if proc is not None:
|
||||
exit_code = proc.poll()
|
||||
if exit_code is not None:
|
||||
parts.append(f"exit code: {exit_code}")
|
||||
if self._stderr_lines:
|
||||
parts.append("stderr tail:\n" + "\n".join(self._stderr_lines))
|
||||
return "\n".join(parts)
|
||||
|
||||
def _default_launch_args(self, env: dict[str, str]) -> tuple[str, ...]:
|
||||
if self.config.dsh_bin is None:
|
||||
try:
|
||||
from deepseek_harness_runtime import resolve_bundled_launch_args
|
||||
except ImportError as exc:
|
||||
raise FileNotFoundError(
|
||||
"Unable to locate the bundled DeepSeek Harness dsh runtime. "
|
||||
"Install deepseek-harness-runtime-bin."
|
||||
) from exc
|
||||
base = resolve_bundled_launch_args()
|
||||
else:
|
||||
base = (str(Path(self.config.dsh_bin).expanduser().resolve()),)
|
||||
|
||||
if self.config.dsh_home is not None:
|
||||
if not self.config.dsh_home.strip():
|
||||
raise ValueError("HarnessConfig requires a non-empty dsh_home")
|
||||
env["DSH_HOME"] = str(Path(self.config.dsh_home).expanduser().resolve())
|
||||
elif not env.get("DSH_HOME", "").strip():
|
||||
raise ValueError(
|
||||
"HarnessConfig requires an explicit dsh_home or non-empty DSH_HOME; "
|
||||
"the Python SDK never uses ~/.dsh implicitly"
|
||||
)
|
||||
|
||||
patches = tuple(
|
||||
argument
|
||||
for patch in self.config.patches
|
||||
for argument in ("--patch", str(Path(patch).expanduser().resolve()))
|
||||
)
|
||||
return (*base, "--profile", self.config.profile, *patches)
|
||||
|
||||
def _unsubscribe_notifications(self, subscription_id: str) -> None:
|
||||
with self._lock:
|
||||
self._notification_subscribers.pop(subscription_id, None)
|
||||
|
||||
def _record_session_relationship_locked(self, notification: Notification) -> None:
|
||||
if notification.method != "subagent.started":
|
||||
return
|
||||
parent_id = notification.payload.get("parentSessionId")
|
||||
child_id = notification.payload.get("childSessionId")
|
||||
if (
|
||||
isinstance(parent_id, str)
|
||||
and parent_id
|
||||
and isinstance(child_id, str)
|
||||
and child_id
|
||||
and parent_id != child_id
|
||||
):
|
||||
self._session_parents[child_id] = parent_id
|
||||
|
||||
def _notification_belongs_to_session_tree(self, session_id: str) -> NotificationFilter:
|
||||
def belongs(notification: Notification) -> bool:
|
||||
payload = notification.payload
|
||||
if notification.method in {"subagent.started", "subagent.finished"}:
|
||||
parent_id = payload.get("parentSessionId")
|
||||
if (
|
||||
isinstance(parent_id, str)
|
||||
and self._session_is_descendant_of(parent_id, session_id)
|
||||
):
|
||||
return True
|
||||
return payload.get("childSessionId") == session_id
|
||||
related_id = payload.get("sessionId")
|
||||
return (
|
||||
isinstance(related_id, str)
|
||||
and self._session_is_descendant_of(related_id, session_id)
|
||||
)
|
||||
|
||||
return belongs
|
||||
|
||||
def _session_is_descendant_of(self, session_id: str, root_session_id: str) -> bool:
|
||||
current = session_id
|
||||
visited: set[str] = set()
|
||||
while current not in visited:
|
||||
if current == root_session_id:
|
||||
return True
|
||||
visited.add(current)
|
||||
parent = self._session_parents.get(current)
|
||||
if parent is None:
|
||||
return False
|
||||
current = parent
|
||||
return False
|
||||
|
||||
|
||||
class NotificationSubscription:
|
||||
def __init__(
|
||||
self,
|
||||
client: HarnessClient,
|
||||
subscription_id: str,
|
||||
notifications: queue.Queue[Notification | BaseException],
|
||||
) -> None:
|
||||
self._client = client
|
||||
self._subscription_id = subscription_id
|
||||
self._notifications = notifications
|
||||
self._closed = False
|
||||
|
||||
def __enter__(self) -> "NotificationSubscription":
|
||||
return self
|
||||
|
||||
def __exit__(self, _exc_type, _exc, _tb) -> None:
|
||||
self.close()
|
||||
|
||||
def close(self) -> None:
|
||||
if self._closed:
|
||||
return
|
||||
self._closed = True
|
||||
self._client._unsubscribe_notifications(self._subscription_id)
|
||||
|
||||
def next(self, timeout_seconds: float | None = None) -> Notification:
|
||||
"""Read one notification; an optional timeout stops only this local wait."""
|
||||
try:
|
||||
item = self._notifications.get(timeout=timeout_seconds)
|
||||
except queue.Empty as exc:
|
||||
raise TimeoutError("timed out waiting for an SDK notification") from exc
|
||||
if isinstance(item, BaseException):
|
||||
raise item
|
||||
return item
|
||||
|
||||
def drain(self, on_notification: Callable[[Notification], None]) -> None:
|
||||
while True:
|
||||
try:
|
||||
item = self._notifications.get_nowait()
|
||||
except queue.Empty:
|
||||
return
|
||||
if isinstance(item, BaseException):
|
||||
raise item
|
||||
on_notification(item)
|
||||
|
||||
|
||||
class _SessionPromptResponse(BaseModel):
|
||||
messageId: str
|
||||
|
||||
|
||||
class _WorkingDirectoryResponse(BaseModel):
|
||||
cwd: str
|
||||
|
||||
|
||||
class _EmptyResponse(BaseModel):
|
||||
pass
|
||||
|
||||
|
||||
def _int_or_none(value: object) -> int | None:
|
||||
return value if isinstance(value, int) else None
|
||||
|
||||
|
||||
def _command_execution(value: JsonValue) -> CommandExecution:
|
||||
"""Decode native command results and report malformed data as a protocol error."""
|
||||
try:
|
||||
return CommandExecution.model_validate(value)
|
||||
except ValidationError as error:
|
||||
raise SdkProtocolError("session/query returned an invalid command result") from error
|
||||
@@ -0,0 +1,23 @@
|
||||
from __future__ import annotations
|
||||
|
||||
|
||||
class HarnessError(Exception):
|
||||
"""Base exception for SDK and runtime failures."""
|
||||
|
||||
|
||||
class TransportClosedError(HarnessError):
|
||||
"""Raised when the runtime subprocess exits or closes stdout."""
|
||||
|
||||
|
||||
class SdkProtocolError(HarnessError):
|
||||
"""Raised when the runtime sends data outside the SDK protocol."""
|
||||
|
||||
|
||||
class JsonRpcError(HarnessError):
|
||||
"""Raised when the runtime returns a JSON-RPC error response."""
|
||||
|
||||
def __init__(self, code: int | None, message: str, data: object | None = None) -> None:
|
||||
super().__init__(message)
|
||||
self.code = code
|
||||
self.message = message
|
||||
self.data = data
|
||||
@@ -0,0 +1,107 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from typing import Annotated, Literal, TypeAlias
|
||||
|
||||
from pydantic import BaseModel, Field, JsonValue as PydanticJsonValue, field_validator
|
||||
|
||||
JsonScalar: TypeAlias = str | int | float | bool | None
|
||||
JsonValue: TypeAlias = JsonScalar | dict[str, "JsonValue"] | list["JsonValue"]
|
||||
JsonObject: TypeAlias = dict[str, JsonValue]
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class Notification:
|
||||
method: str
|
||||
payload: JsonObject
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class IncomingRequest:
|
||||
id: str | int
|
||||
method: str
|
||||
payload: JsonObject
|
||||
|
||||
|
||||
class ServerInfo(BaseModel):
|
||||
name: str | None = None
|
||||
version: str | None = None
|
||||
|
||||
|
||||
class InitializeResponse(BaseModel):
|
||||
serverInfo: ServerInfo | None = None
|
||||
|
||||
|
||||
class CommandSuccessResult(BaseModel):
|
||||
"""Successful handler result, optionally linked to a Session event."""
|
||||
|
||||
kind: Literal["success"]
|
||||
text: str | None = None
|
||||
source_event_seq: int | None = Field(default=None, alias="sourceEventSeq", strict=True, ge=0, le=2**53 - 1)
|
||||
|
||||
@field_validator("text", "source_event_seq", mode="before")
|
||||
@classmethod
|
||||
def _reject_null(cls, value: object) -> object:
|
||||
if value is None:
|
||||
raise ValueError("optional command result fields must be omitted instead of null")
|
||||
return value
|
||||
|
||||
|
||||
class CommandErrorResult(BaseModel):
|
||||
"""A command handler's reported failure."""
|
||||
|
||||
kind: Literal["error"]
|
||||
text: str
|
||||
|
||||
@field_validator("text")
|
||||
@classmethod
|
||||
def _non_blank_text(cls, value: str) -> str:
|
||||
if not value.strip():
|
||||
raise ValueError("command error text must not be blank")
|
||||
return value
|
||||
|
||||
|
||||
CommandResult: TypeAlias = Annotated[CommandSuccessResult | CommandErrorResult, Field(discriminator="kind")]
|
||||
|
||||
|
||||
class CommandExecution(BaseModel):
|
||||
"""Settled command result and the id pairing its command/run and command/done events."""
|
||||
|
||||
command_id: str = Field(alias="commandId", min_length=1)
|
||||
result: CommandResult
|
||||
|
||||
|
||||
class ApprovalRequestParams(BaseModel):
|
||||
"""Server-to-client approval/request payload after explicit handshake opt-in."""
|
||||
|
||||
sessionId: str
|
||||
toolName: str
|
||||
callId: str | None = None
|
||||
reason: str | None = None
|
||||
|
||||
|
||||
class ApprovalRequestResult(BaseModel):
|
||||
"""One-operation decision; allowed-once is the only grant."""
|
||||
|
||||
outcome: Literal["allowed-once", "rejected", "cancelled"]
|
||||
|
||||
class UserQuestionRequest(BaseModel):
|
||||
"""Runtime question batch; questions retain their options, detail, and presentation intent."""
|
||||
|
||||
request_id: str = Field(alias="requestId", min_length=1)
|
||||
session_id: str = Field(alias="sessionId")
|
||||
questions: list[dict[str, PydanticJsonValue]] = Field(min_length=1)
|
||||
|
||||
|
||||
class UserQuestionAnswerItem(BaseModel):
|
||||
"""Answer to one original question id, using selected labels or custom text."""
|
||||
|
||||
id: str
|
||||
selected: list[str]
|
||||
custom: str | None = None
|
||||
|
||||
|
||||
class UserQuestionAnswer(BaseModel):
|
||||
"""One answer per original question; an empty batch is not an implicit approval."""
|
||||
|
||||
answers: list[UserQuestionAnswerItem]
|
||||
@@ -0,0 +1,219 @@
|
||||
"""Local Office operations through the runtime wheel's dsoffice CLI.
|
||||
|
||||
Calls are synchronous and do not create agents, sessions, or model requests.
|
||||
The CLI owns conversion deadlines, engine termination, and failed-output cleanup.
|
||||
Console Ctrl+C waits for CLI cleanup before raising KeyboardInterrupt; a second
|
||||
interrupt forces termination and can leave partial output. On Windows, callers
|
||||
must share the CLI's console for Ctrl+C delivery.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
from collections.abc import Sequence
|
||||
from dataclasses import dataclass, fields
|
||||
from pathlib import Path
|
||||
from typing import Literal, TypeVar
|
||||
|
||||
import deepseek_harness_runtime
|
||||
from deepseek_harness_runtime._resources import run_office_process
|
||||
from pydantic import BaseModel, ConfigDict, Field, ValidationError
|
||||
|
||||
from .errors import HarnessError, SdkProtocolError
|
||||
|
||||
|
||||
class OfficeError(HarnessError):
|
||||
"""A failed Office operation, including its CLI error code and exit status."""
|
||||
|
||||
def __init__(self, code: str, message: str, exit_code: int) -> None:
|
||||
super().__init__(message)
|
||||
self.code = code
|
||||
self.exit_code = exit_code
|
||||
|
||||
|
||||
class _OfficeModel(BaseModel):
|
||||
model_config = ConfigDict(strict=True, frozen=True)
|
||||
|
||||
|
||||
class ConversionResult(_OfficeModel):
|
||||
"""Saved conversion or recalculation output and missing declared fonts."""
|
||||
|
||||
backend: Literal["native", "wasm"]
|
||||
output_path: Path = Field(alias="outputPath")
|
||||
missing_fonts: list[str] = Field(alias="missingFonts")
|
||||
|
||||
|
||||
class ImageRectangle(_OfficeModel):
|
||||
"""Source rectangle in CSS pixels at 96 DPI, before raster scaling."""
|
||||
|
||||
x: float
|
||||
y: float
|
||||
width: float
|
||||
height: float
|
||||
|
||||
|
||||
class RenderedImage(_OfficeModel):
|
||||
"""One saved PNG and its source page, worksheet, or worksheet fragment."""
|
||||
|
||||
index: int
|
||||
path: Path
|
||||
width: int
|
||||
height: int
|
||||
rectangle: ImageRectangle
|
||||
byte_length: int = Field(alias="byteLength")
|
||||
page: int | None = None
|
||||
sheet: str | None = None
|
||||
range: str | None = None
|
||||
rtl: bool | None = None
|
||||
|
||||
|
||||
class RenderImagesResult(_OfficeModel):
|
||||
"""Image manifest for one saved input; page_count includes unselected pages."""
|
||||
|
||||
schema_version: Literal[1] = Field(alias="schemaVersion")
|
||||
backend: Literal["native", "wasm"]
|
||||
raster_engine: Literal["libreoffice", "pdfium"] = Field(alias="rasterEngine")
|
||||
source: Literal["saved"]
|
||||
input_path: Path = Field(alias="inputPath")
|
||||
source_sha256: str = Field(alias="sourceSha256")
|
||||
dpi: float
|
||||
page_count: int = Field(alias="pageCount")
|
||||
images: list[RenderedImage]
|
||||
missing_fonts: list[str] = Field(alias="missingFonts")
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class OfficeOptions:
|
||||
"""Kit limits and fonts; omitted values retain the installed kit defaults.
|
||||
|
||||
timeout_ms bounds the engine operation, including font work and output,
|
||||
after explicit resource download. The call waits for engine exit and cleanup.
|
||||
Font paths may be relative to cwd; fallback groups replace the kit defaults.
|
||||
"""
|
||||
|
||||
timeout_ms: int | None = None
|
||||
max_input_bytes: int | None = None
|
||||
max_output_bytes: int | None = None
|
||||
max_image_resolution: int | None = None
|
||||
max_archive_entries: int | None = None
|
||||
max_uncompressed_bytes: int | None = None
|
||||
max_font_files: int | None = None
|
||||
max_font_file_bytes: int | None = None
|
||||
max_loaded_font_bytes: int | None = None
|
||||
font_directories: Sequence[str | os.PathLike[str]] | None = None
|
||||
initial_font_families: Sequence[str] | None = None
|
||||
font_fallbacks: Sequence[Sequence[str]] | None = None
|
||||
|
||||
def _arguments(self) -> list[str]:
|
||||
arguments: list[str] = []
|
||||
for field in fields(self):
|
||||
value = getattr(self, field.name)
|
||||
if value is None:
|
||||
continue
|
||||
if field.name == "font_directories":
|
||||
for path in value:
|
||||
arguments.extend(("--font-directory", os.fspath(path)))
|
||||
elif field.name == "initial_font_families":
|
||||
for family in value:
|
||||
arguments.extend(("--initial-font-family", family))
|
||||
elif field.name == "font_fallbacks":
|
||||
arguments.extend(("--font-fallbacks", json.dumps(value)))
|
||||
else:
|
||||
arguments.extend(("--" + field.name.replace("_", "-"), str(value)))
|
||||
return arguments
|
||||
|
||||
|
||||
class _CliFailure(_OfficeModel):
|
||||
code: str
|
||||
error: str
|
||||
|
||||
|
||||
_Result = TypeVar("_Result", bound=_OfficeModel)
|
||||
|
||||
|
||||
def _run(arguments: list[str], options: OfficeOptions | None, result_type: type[_Result]) -> _Result:
|
||||
process = run_office_process(
|
||||
[*deepseek_harness_runtime.resolve_office_launch_args(), *arguments,
|
||||
*(options._arguments() if options is not None else [])],
|
||||
)
|
||||
stdout, stderr = process.stdout, process.stderr
|
||||
if process.returncode != 0:
|
||||
try:
|
||||
failure = _CliFailure.model_validate_json(stderr)
|
||||
except ValidationError:
|
||||
raise OfficeError("failed", stderr.decode("utf-8", errors="replace").strip()
|
||||
or "Office CLI exited without a diagnostic.",
|
||||
process.returncode) from None
|
||||
raise OfficeError(failure.code, failure.error, process.returncode)
|
||||
try:
|
||||
return result_type.model_validate_json(stdout)
|
||||
except ValidationError as error:
|
||||
raise SdkProtocolError("Office CLI returned an invalid result.") from error
|
||||
|
||||
|
||||
def render_images(
|
||||
input_path: str | os.PathLike[str],
|
||||
output_dir: str | os.PathLike[str],
|
||||
*,
|
||||
pages: Literal["all"] | Sequence[int] | None = None,
|
||||
sheet: str | None = None,
|
||||
range: str | None = None,
|
||||
dpi: int | None = None,
|
||||
max_pages: int | None = None,
|
||||
max_pixels: int | None = None,
|
||||
max_dimension: int | None = None,
|
||||
options: OfficeOptions | None = None,
|
||||
) -> RenderImagesResult:
|
||||
"""Render Office or PDF to PNG files and manifest.json in a fresh directory.
|
||||
|
||||
Pages are one-based document pages or slides. Worksheets use an exact
|
||||
sheet name and optional A1 range instead. Paths may be relative to cwd.
|
||||
The caller owns successful output; failed batches remove the new directory.
|
||||
Raises OfficeError for CLI failures and SdkProtocolError for invalid JSON.
|
||||
"""
|
||||
arguments = ["render", "--input", os.fspath(input_path), "--output-dir", os.fspath(output_dir)]
|
||||
selections = {
|
||||
"pages": pages if isinstance(pages, str) or pages is None else ",".join(map(str, pages)),
|
||||
"sheet": sheet, "range": range, "dpi": dpi, "max-pages": max_pages,
|
||||
"max-pixels": max_pixels, "max-dimension": max_dimension,
|
||||
}
|
||||
for name, value in selections.items():
|
||||
if value is not None:
|
||||
arguments.extend(("--" + name, str(value)))
|
||||
return _run(arguments, options, RenderImagesResult)
|
||||
|
||||
|
||||
def convert(
|
||||
input_path: str | os.PathLike[str],
|
||||
output_path: str | os.PathLike[str],
|
||||
*,
|
||||
sheet: str | None = None,
|
||||
options: OfficeOptions | None = None,
|
||||
) -> ConversionResult:
|
||||
"""Export Office to the format named by a fresh output file's extension.
|
||||
|
||||
Paths may be relative to cwd. CSV export requires an exact sheet name for
|
||||
multi-sheet input. Existing output is rejected; failed output is removed.
|
||||
Raises OfficeError for CLI failures and SdkProtocolError for invalid JSON.
|
||||
"""
|
||||
arguments = ["convert", "--input", os.fspath(input_path), "--output", os.fspath(output_path)]
|
||||
if sheet is not None:
|
||||
arguments.extend(("--sheet", sheet))
|
||||
return _run(arguments, options, ConversionResult)
|
||||
|
||||
|
||||
def recalculate(
|
||||
input_path: str | os.PathLike[str],
|
||||
output_path: str | os.PathLike[str],
|
||||
*,
|
||||
options: OfficeOptions | None = None,
|
||||
) -> ConversionResult:
|
||||
"""Refresh workbook formula caches into a distinct, fresh XLSX or ODS file.
|
||||
|
||||
Input accepts XLS, XLSX, or ODS. Paths may be relative to cwd. Formulas
|
||||
survive, but recalculation does not verify business logic or Excel fidelity.
|
||||
Raises OfficeError for CLI failures and SdkProtocolError for invalid JSON.
|
||||
"""
|
||||
return _run(["recalculate", "--input", os.fspath(input_path), "--output", os.fspath(output_path)],
|
||||
options, ConversionResult)
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"repository": "https://github.com/deepseek-ai/deepseek-harness",
|
||||
"commit": "fcc0ad462172522aaf5c93a7b2e01f6b9f0b0159",
|
||||
"archiveSha256": "44926eb97c791d1b7a640a0146aa1c522aae7c21a8e238576820d01445cff976",
|
||||
"sdkFiles": {
|
||||
"__init__.py": "e03dffd1ac4a6e301064e209b1882965c8e78d90e30b19d0d7c9cd7e935c29ff",
|
||||
"api.py": "9c772909775196fc4070182191738ad227a3bfdccc68d1b6f4e8b90dec08430b",
|
||||
"client.py": "e0bdbf82d5932d38bb38a2eb8b2ae123487c7c520444c64c859c70e4504028da",
|
||||
"errors.py": "0d380a8947c7cc64dc1811660816b89fe676fac46b3cfcf18a51ecafc6bf28da",
|
||||
"models.py": "9b10f6d0b95356f8cd903ba2e897c794d305d17da2cfcc135ccea8c4384b548f",
|
||||
"office.py": "300d51a882f321d4f417b0c1b9d3ab8e04455e6c8533da858d1d57e8ed30018a"
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user