Phase 003: remove the coding-agent and ekko-agent runtimes

Every chat session now runs through the Hermes bridge, so the three chat
chains become feature-equivalent instead of three partially-maintained
dispatch paths. Keeping the coding-agent and in-house agent runtimes alive
meant every bridge change had to be mirrored into two more runtimes that
had already drifted.

Historical rows are read, not migrated: sessions stored with the retired
source normalize to cli on load, workflow graphs naming the retired agents
keep loading and run on the bridge, and the visible-source check plus
SOURCE_LABELS still recognize the old value so those sessions stay listed.

The public surface follows the code: the OpenAPI generator and the MCP
chat-run tool schema drop the six retired entry fields so external callers
are not told about runtimes that no longer exist.

harness-check gains a RETIRED_RUNTIME scan so the residual check is a
mechanical gate instead of a manual grep, with the two surviving read-side
compat sites recorded with reasons.

Refs: docs/phases/phase_003.md
This commit is contained in:
2026-10-16 13:27:50 +08:00
parent c93e1fe1bd
commit 8c1ddf415f
123 changed files with 567 additions and 23599 deletions
@@ -0,0 +1,107 @@
---
date: 2026-10-16
pr: pending
feature: Phase 003 - remove the coding-agent and ekko-agent runtimes
impact: Every chat session now runs through the Hermes bridge; sessions stored with the old `coding_agent` source are normalized to `cli` on load.
---
# Phase 003 — Remove the coding-agent and ekko-agent runtimes
Phase: `docs/phases/phase_003.md` (groups I and J)
## What Changed
The chat chain had three dispatch branches: bridge, coding agent (Claude Code /
Codex), and ekko-agent. Phase 003 deletes the latter two, leaving the bridge as
the single execution path.
### Deleted modules
- `packages/server/src/services/agent-runner/` — 13 files. Adapters for the
Anthropic and OpenAI Responses streaming shapes, the Claude Code / Codex HTTP
proxies, the SSE helpers, and `coding-agent-run-manager`.
- `packages/server/src/services/ekko-agent/` — 2 files (`manager.ts`, `mcp.ts`).
- `packages/ekko-agent/` — the in-house agent runtime package.
- `run-chat/handle-coding-agent-run.ts`, `run-chat/handle-ekko-agent-run.ts`.
- `run-chat/sse-utils.ts` — an orphan that only re-exported
`agent-runner/sse`. No production module imported it; the single remaining
reference was a `vi.mock` in `run-chat-load-state.test.ts`.
- The three route modules, the controller, the service, `CodingAgentsView.vue`,
and `packages/client/src/api/coding-agents.ts`.
### Dispatch
`runAndWait` in `run-chat/index.ts` was a three-way branch. It is now a single
call to `handleBridgeRun`. Two predicates went away with it:
- `isCodingAgentExecution(source, data)`
- `isEkkoAgentExecution(data)`
`isWorking` was computed as `!isCodingAgentExecution(...)` at three call sites
(queue start, direct run start, resumed run). All three are now `true`.
### Types and session fields
- `ChatCodingAgentId` — defined twice (server `run-chat/types.ts`, client
`api/coding-agents.ts`). Both definitions are gone; nothing imports them now.
- `ChatRunSource` lost `'coding_agent'`.
- `QueuedRun` lost `codingAgentId` / `agentId`.
- `StartRunRequest` lost `coding_agent_id` / `agent_id`.
- The client `Session` shape lost `codingAgentId` / `codingAgentMode`.
### `ChatRunSource` compatibility
`resolveRunSource` previously passed `'coding_agent'` through. It now falls
through to the default `'cli'`, so sessions stored with the old source run
through the bridge without a data migration. The same is true for the
value-based checks in `controllers/hermes/sessions.ts` — they read the stored
string, and any source that is not `global_agent` or `workflow` resolves to the
bridge path.
`isCodingAgentSession` in the sessions controller controlled three things at
once: whether a workspace was created, whether the bridge was notified of a
model change, and whether `agent_native_session_id` was cleared. All three now
apply to every session, which is the intended post-Phase-003 behavior.
### Workflow
`WorkflowNodeAgent` narrowed to `'hermes'`. `resolveWorkflowNodeRunTarget`
ignores its argument and always returns the Hermes target, so saved workflows
that still name `claude-code` or `codex` keep loading. The node editor's
protocol dropdown and the `apiModeRequired` validation were removed, along with
the `apiMode` field on `WorkflowAgentNodeData`.
### Usage recording
`RecordSessionUsageInput.source` and `.agent` narrowed to `'hermes'`. The only
caller is `handle-bridge-run.ts`, which already passed those values. Rows
written before this phase keep their stored `source` / `agent` strings; the
client's `AgentBreakdown` maps anything it does not recognize to `unknown`.
## Contract Check
`/chat-run` event names, field names, and field types are unchanged. The
`socket.start_run` payload only ever sent `coding_agent_id` / `agent_id` for
sessions that were already coding-agent sessions; nothing new is sent. Two
optional request fields were removed, and every session that used them now
takes the bridge path instead.
## Residual Strings
Kept on purpose, so existing records still render a sensible label:
- `packages/client/src/shared/session-display.ts` — `coding_agent: 'Coding Agent'`
in `SOURCE_LABELS`, which labels sessions already stored in the DB.
- `packages/server/src/controllers/hermes/sessions.ts` — the
`isVisibleWebUiSessionSource` check still lists `'coding_agent'` so old
sessions stay visible in the Web UI session list.
Both are registered in the `scripts/harness-check.mjs` allow-list.
## Verification
```bash
npm run harness:check
npm run build
npm run test
```
+6 -546
View File
@@ -156,10 +156,6 @@
"name": "Devices",
"description": "Device pairing and LAN peer operations"
},
{
"name": "Coding Agents",
"description": "Coding agent installation, config, and runs"
},
{
"name": "API Docs",
"description": "OpenAPI route catalog"
@@ -871,17 +867,18 @@
"type": "string",
"enum": [
"cli",
"coding_agent",
"global_agent"
"global_agent",
"workflow"
],
"description": "Run backend source. Use cli for Hermes bridge runs, coding_agent for Claude Code/Codex, or global_agent for global-agent sessions. Omit source for normal Hermes chat runs; do not use the legacy api_server source."
"description": "Run backend source. Use cli for Hermes bridge runs or global_agent for global-agent sessions. Omit source for normal Hermes chat runs; do not use the legacy api_server source."
},
"session_source": {
"type": "string",
"enum": [
"global_agent"
"global_agent",
"workflow"
],
"description": "Marks a coding-agent or bridge session as launched from the global agent."
"description": "Marks the session as launched from the global agent or from a workflow run."
},
"instructions": {
"type": "string",
@@ -896,47 +893,6 @@
"type": "string",
"description": "Optional per-run reasoning effort override."
},
"coding_agent_id": {
"type": "string",
"enum": [
"claude-code",
"codex"
],
"description": "Coding agent id when source is coding_agent."
},
"agent_id": {
"type": "string",
"enum": [
"claude-code",
"codex"
],
"description": "Alias for coding_agent_id."
},
"mode": {
"type": "string",
"enum": [
"scoped",
"global"
],
"description": "Coding-agent launch mode."
},
"baseUrl": {
"type": "string",
"description": "Optional provider base URL for coding-agent runs."
},
"apiKey": {
"type": "string",
"description": "Optional provider API key for coding-agent runs."
},
"apiMode": {
"type": "string",
"enum": [
"chat_completions",
"codex_responses",
"anthropic_messages"
],
"description": "Optional provider wire API mode for coding-agent runs."
},
"timeout_ms": {
"type": "integer",
"minimum": 1,
@@ -1013,502 +969,6 @@
}
}
},
"/api/coding-agents": {
"get": {
"tags": [
"Coding Agents"
],
"summary": "Get coding-agents",
"description": "GET /api/coding-agents",
"operationId": "status",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Success"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not found"
}
}
}
},
"/api/coding-agents/runs/{sessionId}": {
"delete": {
"tags": [
"Coding Agents"
],
"summary": "Delete :sessionId",
"description": "DELETE /api/coding-agents/runs/:sessionId",
"operationId": "stopRun",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Success"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"parameters": [
{
"name": "sessionId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/api/coding-agents/runs/{sessionId}/input": {
"post": {
"tags": [
"Coding Agents"
],
"summary": "Create input",
"description": "POST /api/coding-agents/runs/:sessionId/input",
"operationId": "sendRunInput",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Success"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"parameters": [
{
"name": "sessionId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"input": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/coding-agents/{id}": {
"delete": {
"tags": [
"Coding Agents"
],
"summary": "Delete :id",
"description": "DELETE /api/coding-agents/:id",
"operationId": "remove",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Success"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/api/coding-agents/{id}/config-files/{key}": {
"get": {
"tags": [
"Coding Agents"
],
"summary": "Get :key",
"description": "GET /api/coding-agents/:id/config-files/:key",
"operationId": "readConfigFile",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Success"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not found"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "key",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"put": {
"tags": [
"Coding Agents"
],
"summary": "Update :key",
"description": "PUT /api/coding-agents/:id/config-files/:key",
"operationId": "writeConfigFile",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Success"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "key",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/coding-agents/{id}/install": {
"post": {
"tags": [
"Coding Agents"
],
"summary": "Create install",
"description": "POST /api/coding-agents/:id/install",
"operationId": "install",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Success"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/api/coding-agents/{id}/launch/native": {
"post": {
"tags": [
"Coding Agents"
],
"summary": "Create native",
"description": "POST /api/coding-agents/:id/launch/native",
"operationId": "nativeLaunch",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Success"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"apiKey": {
"type": "string"
},
"apiMode": {
"type": "object",
"additionalProperties": true
},
"baseUrl": {
"type": "string"
},
"mode": {
"type": "object",
"additionalProperties": true
},
"model": {
"type": "string"
},
"profile": {
"type": "string"
},
"provider": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/coding-agents/{id}/launch/prepare": {
"post": {
"tags": [
"Coding Agents"
],
"summary": "Create prepare",
"description": "POST /api/coding-agents/:id/launch/prepare",
"operationId": "prepareLaunch",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Success"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"apiKey": {
"type": "string"
},
"apiMode": {
"type": "object",
"additionalProperties": true
},
"baseUrl": {
"type": "string"
},
"mode": {
"type": "object",
"additionalProperties": true
},
"model": {
"type": "string"
},
"profile": {
"type": "string"
},
"provider": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/coding-agents/{id}/runs": {
"post": {
"tags": [
"Coding Agents"
],
"summary": "Create runs",
"description": "POST /api/coding-agents/:id/runs",
"operationId": "startRun",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Success"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"apiKey": {
"type": "string"
},
"apiMode": {
"type": "object",
"additionalProperties": true
},
"baseUrl": {
"type": "string"
},
"mode": {
"type": "object",
"additionalProperties": true
},
"model": {
"type": "string"
},
"profile": {
"type": "string"
},
"provider": {
"type": "string"
},
"sessionId": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/cron-history": {
"get": {
"tags": [
+4 -5
View File
@@ -158,10 +158,9 @@ isEkkoAgentExecution()
```bash
cd /Users/jack/source/MyProject/js/hermes-ui
# 残留检查
grep -rn "coding_agent\|codingAgent\|CodingAgent\|ekko-agent\|ekkoAgent\|EkkoAgent" \
packages/ tests/ --include="*.ts" --include="*.vue" --include="*.json"
# 期望:零命中
# 残留检查(harness 机械门禁,RETIRED_RUNTIME_ALLOWED 登记保留理由)
npm run harness:check
# 期望:Harness check passed
npm run build
npm run test
@@ -184,7 +183,7 @@ npm run test:e2e
| # | 风险 | 缓解 |
|---|---|---|
| P3-1 | `isWorking` 三处漏改 → 聊天状态卡死或一直转圈 | `grep -n isCodingAgentExecution` 必须零命中后才算改完 |
| P3-1 | `isWorking` 三处漏改 → 聊天状态卡死或一直转圈 | `npm run harness:check` 的 RETIRED_RUNTIME 扫描必须零命中 |
| P3-2 | 历史会话带 `coding_agent_id` 导致渲染报错 | 读侧容忍未知字段;手工造一条旧会话验证 |
| P3-3 | 删 `agent-runner/` 时误删共用工具 | 先 `grep -rn "agent-runner"` 确认引用方只在这两组内 |
| P3-4 | e2e 有用例依赖 coding-agents API | `npm run test:e2e` 必跑,红了删对应用例 |