Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
651 changes: 494 additions & 157 deletions apps/api/src/opendirector_api/agent.py

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions docs/architecture/agent-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Harness 指承担模型调用、工具执行和上下文管理的 Agent 执行
| --- | --- | --- |
| Default | 固定版本的 bundled OpenCode | OpenDirector 模型配置,经本地模型代理访问服务 |
| OpenCode CLI | opencode,优先 PATH,再查找常见 CLI 安装目录 | CLI 原生配置与模型目录 |
| Codex | 优先 PATH 中的 codex,再查找常见桌面版与 CLI 安装目录 | 原生认证与模型目录;隔离启动前解析所选模型或默认模型 |
| Codex | 优先 PATH 中的 codex,再查找常见桌面版与 CLI 安装目录;以 `app-server` 常驻进程通信,沙箱与审批策略作为协议参数传入 | 原生认证与模型目录;隔离启动前解析所选模型或默认模型 |
| Claude Code | claude,优先 PATH,再查找常见 CLI 安装目录 | 原生认证、环境变量与初始化模型目录 |
| JiuwenSwarm | jiuwenswarm-process,优先 PATH,再查找常见 CLI 安装目录,通过 stdin/stdout JSONL 直接调用 | 本机 Jiuwen 模型目录、配置与环境变量 |
| DeepSeek Harness | dsh,优先 PATH,再查找常见 CLI 安装目录,以 acp profile 运行标准 JSON-RPC | CLI 原生 profile、模型目录与认证 |
Expand Down Expand Up @@ -51,7 +51,7 @@ Default 将模型配置中的输入模态传入 bundled OpenCode。外部 harnes

Search citations keep their native markers in the original reply and trace. Completed Codex MCP web-search results supply validated source IDs, HTTP(S) URLs and titles through `sources` events; the conversation retains this metadata with the reply. The UI splits tool activities using raw text offsets before formatting prose citations as source links, and uses the same formatting for copying. Code examples remain literal. Missing sources and incomplete final markers have a localized fallback. For saved Codex replies without source metadata, queries derive it from the matching turn's project-local trace without rewriting the conversation; a bounded metadata cache is invalidated by trace modification time and size. Reading a trace never requests a model call.

同一工程同时只接受一个回复运行。运行事件转换为回复正文和工具活动,保存到对应会话;原生事件与业务工具事件追加到 `agent-runs/<turn-id>.<runtime>.jsonl`。Default 使用 `opencode` 作为轨迹文件的 runtime 名称。
同一工程同时只执行一个回复。运行期间仍可提交补充消息:`POST /assistant/messages` 在空闲时直接开始一轮,在运行中返回 202 并按 `queueSeq` 把消息排入投递队列,本轮结束后依次运行。`end` 事件带 `nextTurnId` 时事件流不关闭,客户端因此能在同一条连接上接着收到下一轮;断线重连用 `GET /turns/{turn_id}/events?after=<seq>` 从已收到的最后一帧续读;链已经推进到下一轮时,客户端手里上一轮的 turn id 同样能找到这条链,不必等页面刷新。排队消息立即出现在会话里并可读;停止时整条链一起停止,排队消息标记为 `cancelled` 并保留下来供用户重新发送。运行中还可以把补充文字直接交给这一轮:`POST /assistant/messages` 带 `delivery: "insert"` 时,文字经 runtime 的原生通道进入正在执行的模型循环,而不是另起一轮,因此这一轮已经做的工作不会重来。插入只接受纯文字,素材与技能要等回复结束后再发;runtime 不支持同轮插入时返回 409 并说明原因,用户可改用排队。Codex 通过 `turn/steer` 提供该通道;其它 runtime 在接入原生通道前一律排队。运行事件转换为回复正文和工具活动,保存到对应会话;原生事件与业务工具事件追加到 `agent-runs/<turn-id>.<runtime>.jsonl`。Default 使用 `opencode` 作为轨迹文件的 runtime 名称。

Default 的模型网关在 `agent-runs/<turn-id>.model.jsonl` 记录实际转发的请求体,包括生效的系统消息、会话上下文、工具 Schema 与模型参数。请求 ID 关联上游 HTTP 状态、响应头等待耗时和传输错误。该文件仅供本地调试,创建权限为 `0600`,不记录 HTTP 鉴权头。回复片段、工具结果和 token 用量仍见原生轨迹。

Expand All @@ -62,7 +62,7 @@ Default 的模型网关在 `agent-runs/<turn-id>.model.jsonl` 记录实际转发
| Harness | 执行约束 |
| --- | --- |
| OpenCode | 工具权限配置开放 Shell、文件读取、已发现技能和业务 CLI |
| Codex | workspace-write 沙箱,开放 Shell 和业务 CLI |
| Codex | `app-server` 以 workspace-write 沙箱、`never` 审批策略启动线程,开放 Shell 和业务 CLI |
| Claude Code | 明确允许 Skill、Bash、Read 和业务 CLI |
| JiuwenSwarm | 明确允许 skill_tool、list_skill、read_file、bash 和业务 CLI |
| DeepSeek Harness | 沿用原生工具与权限;Skill 限于本轮快照,业务操作通过 Shell 调用 opendirector,未承接的审批不自动批准 |
Expand Down
164 changes: 164 additions & 0 deletions packages/core/src/opendirector/agent/appserver.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
"""Codex app-server: one turn over the JSON-RPC stdio protocol.

`codex exec` reads one prompt from stdin and exits, so once a turn is running
nothing can reach the model. The app server is the same engine behind a
long-lived channel: a turn can be steered while it runs, and the conversation
keeps a thread id that a later turn can resume.
"""
import asyncio
import json
from collections.abc import Awaitable, Callable
from pathlib import Path

from opendirector.domain.projects import ProjectError

Emit = Callable[[dict], Awaitable[None]]

CLIENT = {'name': 'OpenDirector', 'version': '1.0'}


class Session:
"""A JSON-RPC channel over the app server's stdin and stdout."""

def __init__(self, process):
self.process = process
self.notes: asyncio.Queue[dict] = asyncio.Queue()
self.pending: dict[int, asyncio.Future] = {}
self.next_id = 0
self.reader = asyncio.create_task(self._read())

async def _read(self):
try:
while line := await self.process.stdout.readline():
try:
data = json.loads(line)
except json.JSONDecodeError:
continue
if 'id' in data:
future = self.pending.pop(data['id'], None)
if future is not None and not future.done():
future.set_result(data)
elif 'method' in data:
self.notes.put_nowait(data)
except (asyncio.CancelledError, ValueError):
return

async def write(self, payload: dict):
self.process.stdin.write(json.dumps(payload).encode() + b'\n')
await self.process.stdin.drain()

async def notify(self, method: str, params: dict | None = None):
await self.write({'jsonrpc': '2.0', 'method': method, 'params': params or {}})

async def call(self, method: str, params: dict, timeout: float = 60) -> dict:
self.next_id += 1
identifier = self.next_id
future = asyncio.get_running_loop().create_future()
self.pending[identifier] = future
await self.write({'jsonrpc': '2.0', 'id': identifier, 'method': method, 'params': params})
try:
data = await asyncio.wait_for(future, timeout)
except TimeoutError:
raise ProjectError('codex app-server 没有响应,请检查登录和网络。', 502) from None
finally:
self.pending.pop(identifier, None)
if 'error' in data:
detail = (data['error'] or {}).get('message') or '未知原因'
raise ProjectError(f'codex app-server 拒绝了 {method}:{detail}', 502)
return data.get('result') or {}

async def close(self):
self.reader.cancel()
await asyncio.gather(self.reader, return_exceptions=True)


async def run(process, *, work: Path, model: str | None, resume: str | None,
prompt: str, fallback: str | None, steer: asyncio.Queue[str] | None,
emit: Emit) -> str:
"""Run one turn and return the thread id that can be resumed later.

`prompt` assumes the native thread is resumed and carries only the newest
message; `fallback` is the same request with the whole history, used when a
saved thread cannot be opened.
"""
session = Session(process)
try:
await session.call('initialize', {'clientInfo': CLIENT})
await session.notify('initialized')
thread, resumed = await _thread(session, work, model, resume)
# The trace keeps the native thread id the way the exec protocol kept
# `thread.started`, so a run stays traceable to its engine session.
await emit({'native': {'type': 'thread.started', 'thread_id': thread}})
started = await session.call('turn/start', {
'threadId': thread, 'input': [{'type': 'text', 'text': prompt if resumed or fallback is None else fallback}],
**({'model': model} if model else {})})
turn = (started.get('turn') or {}).get('id')
if not turn:
raise ProjectError('codex 没有开始这一轮回复。', 502)
await _drive(session, thread, turn, steer, emit)
return thread
finally:
await session.close()


async def _thread(session: Session, work: Path, model: str | None,
resume: str | None) -> tuple[str, bool]:
settings = {'cwd': str(work), 'approvalPolicy': 'never', 'sandbox': 'workspace-write',
**({'model': model} if model else {})}
if resume:
try:
result = await session.call('thread/resume', {'threadId': resume, **settings})
thread = (result.get('thread') or {}).get('id')
if thread:
return thread, True
except ProjectError:
# A stale thread id is not fatal: the turn starts over with the full
# authoritative history instead of quietly losing the conversation.
pass
result = await session.call('thread/start', settings)
thread = (result.get('thread') or {}).get('id')
if not thread:
raise ProjectError('codex 没有建立会话。', 502)
return thread, False


async def _drive(session: Session, thread: str, turn: str,
steer: asyncio.Queue[str] | None, emit: Emit):
note = asyncio.create_task(session.notes.get())
wanted = asyncio.create_task(steer.get()) if steer is not None else None
streamed: set[str] = set()
try:
while True:
waiting = {task for task in (note, wanted) if task is not None}
done, _ = await asyncio.wait(waiting, return_when=asyncio.FIRST_COMPLETED)
if wanted is not None and wanted in done:
text = wanted.result()
await session.call('turn/steer', {
'threadId': thread, 'expectedTurnId': turn,
'input': [{'type': 'text', 'text': text}]})
wanted = asyncio.create_task(steer.get())
if note in done:
message = note.result()
note = asyncio.create_task(session.notes.get())
method = message.get('method')
params = message.get('params') or {}
if method == 'item/agentMessage/delta':
if params.get('itemId'):
streamed.add(params['itemId'])
await emit({'type': 'delta', 'text': params.get('delta', '')})
elif method == 'item/completed':
item = params.get('item') or {}
if item.get('type') == 'agentMessage' and item.get('id') not in streamed:
await emit({'type': 'delta', 'text': item.get('text', '')})
elif method == 'turn/completed':
finished = params.get('turn') or {}
status = finished.get('status')
if status == 'failed':
detail = (finished.get('error') or {}).get('message') or '未知原因'
raise ProjectError(f'codex 运行失败:{detail}', 502)
return
finally:
for task in (note, wanted):
if task is not None:
task.cancel()
await asyncio.gather(*[task for task in (note, wanted) if task is not None], return_exceptions=True)
3 changes: 3 additions & 0 deletions packages/core/src/opendirector/agent/context.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
"""Shared input contract for SDK, CLI and service-backed runtimes."""
import asyncio
import json
from dataclasses import dataclass, field
from pathlib import Path
Expand Down Expand Up @@ -28,6 +29,8 @@ class RunContext:
thinking: str = 'auto'
runtime_model: str | None = None
skills: list[dict[str, str]] = field(default_factory=list)
# Text handed to a runtime that can reach the model inside a running turn.
steer: asyncio.Queue[str] | None = None

def native_session_path(self) -> Path | None:
if self.conversation_id is None:
Expand Down
Loading
Loading