Skip to content
Merged
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
51 changes: 33 additions & 18 deletions docs/architecture/rfcs/harness-selection-dsh-pi-v0.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,9 @@ dated 2026-09-15 and is written to land with the managed stack:

| Role | Source | Selection today | Promotion gate |
| --- | --- | --- | --- |
| Default managed execution host | LoopX Turn plus the `dsh` host adapter, bound to an operator-supplied model endpoint | shipped product default: `dsh` for bounded managed Turns, environment-independent; `LOOPX_TURN_HOST` re-points it and an explicit `--host` wins (PR #4443) | keep the typed host request/result, independent validation, and the operator-owned credential boundary; do not replace it without an equal or stronger contract |
| Default managed execution host | LoopX Turn plus the `dsh` host adapter, bound to an operator-supplied model endpoint | shipped product default, credential-resolved: the managed `dsh` host when the operator credential is configured, the individual `codex-cli` host when it is not; `LOOPX_TURN_HOST` re-points whichever resolved and an explicit `--host` wins (PR #4443, default resolution with this change) | keep the typed host request/result, independent validation, and the operator-owned credential boundary; do not replace it without an equal or stronger contract |
| Steward channel executor | the interactive Chat transport the steward answers on | shipped product default, credential-conditional: the managed host (`dsh`) when the operator credential is configured, `codex` when it is not; `LOOPX_MANAGER_ENDPOINT` re-points it and an explicit endpoint wins; selection landed in PR #4446, the conditional default and the segment transport land with this change | the segment transport's typed limits (no streaming, no cross-turn host session, read-only sandbox) stay disclosed and read back, and no managed lane may depend on an individual subscription |
| Supported alternative Turn host | LoopX Turn plus the `codex-cli` adapter | explicitly selectable; it is the `individual` executor kind, so it is billed to one person's CLI login | no managed lane may silently depend on an individual's personal CLI subscription; an individual lane must be selected, not reached by default |
| Supported alternative Turn host | LoopX Turn plus the `codex-cli` adapter | explicitly selectable, and the credential-resolved default of the managed row above on a machine with no operator credential; it is the `individual` executor kind, so it is billed to one person's CLI login | no managed lane may *silently* depend on an individual's personal CLI subscription: the individual host is reached only as that credential-resolved default and is read back as `no_operator_credential`, never substituted for a host the operator selected |
| L1 event source and session-owning runtime candidate | DSH | opt-in, not promoted; the bounded Turn host role is the default row above | the C0, C1, overhead, retention and Mode B rows in this document being run and reviewed |
| Optional visible host loop | Pi | not a managed runtime | declare a per-binding session mode with readback, prove single-executor behavior under restart, "conversation is not a receipt", non-authoritative host-local state, and one real-host restart row |

Expand All @@ -76,14 +76,24 @@ Flash) at reasoning effort `high`, an endpoint from the operator environment
(`DEEPSEEK_API_KEY`).

LoopX **selects** the default host for bounded managed Turns and never infers it
(`loopx/control_plane/turn_driver/host_binding.py`): the shipped default is `dsh`,
`LOOPX_TURN_HOST` re-points it, and an explicit `--host` wins over both. The
operator credential is not a selection input. This distinction is the whole
point of the binding: discovering a key is not a decision to change where work
runs, and a surface that resolves its host from the environment makes a chosen
configuration indistinguishable from an incidental one. A lane selected onto the
DSH host therefore never depends on an individual developer's CLI subscription
being available, funded, or logged in.
from a launch-time surprise (`loopx/control_plane/turn_driver/host_binding.py`):
an explicit `--host` or `LOOPX_TURN_HOST` always wins, and only when neither is
configured is the shipped default resolved from the operator's own credential
facts -- the managed `dsh` host when a credential exists, and the individual
`codex-cli` host when one does not, because an unauthenticated managed host
would refuse to run. The distinction that matters is between a *default* and a
*decision*: a credential may resolve a default that would otherwise have to pick
a host at random, but it never re-points a host the operator already selected.
A lane resolved onto the DSH host therefore never depends on an individual
developer's CLI subscription being available, funded, or logged in, and a lane
without an operator credential never silently borrows one either.

This change also rewrites the promotion gate on the supported alternative host
in the table above. It read "an individual lane must be selected, not reached by
default", which the credential-resolved default contradicts. The rewritten rule
keeps the original intent -- no lane may depend on one person's login without
the operator being able to see that it did -- and names the readback that makes
the dependency visible instead of forbidding the disclosed default.

The steward channel is a **different** surface, and after the revision recorded
below its default is stated as one conditional rule instead of one host name:
Expand All @@ -107,14 +117,19 @@ effort `high`, overridable by `LOOPX_TURN_PROVIDER` / `LOOPX_TURN_MODEL` /
when it is not the shipped one; it is one line because every plan payload carries
it and the agent-facing output budget is a contract, and whichever values the
line names are the values that run, so an owner-set model appears as itself.
Credentials authenticate the selected profile; they never choose it.
Credentials authenticate the selected profile and never choose it; the one
thing a credential resolves is the shipped *host* default of a bounded Turn
nobody selected, and that resolution carries its own readback source.

Evidence for this binding, separated by source:

- repository-covered without any provider call: the shipped default is `dsh`, an
explicit `LOOPX_TURN_HOST` re-points it, an explicit `--host` still wins, and a
configured credential changes none of those selections (tests in PR #4443, not
yet on `main`);
- repository-covered without any provider call: with an operator credential the
shipped default is `dsh` and without one it is `codex-cli`, an explicit
`LOOPX_TURN_HOST` re-points either default, and an explicit `--host` still
wins over all of them (`tests/test_turn_default_host_binding.py`,
`tests/test_turn_managed_executor_binding.py`,
`examples/loopx-turn-managed-executor-binding-smoke.py`,
`examples/loopx-turn-managed-default-flow-smoke.py`);
- local live qualification with the real SDK and runtime
(`deepseek-harness-sdk==0.1.5rc1`, the pin PR #4420 proposes; `main` still
pins `0.1.2a3` and the same pair also passed there): the in-process
Expand Down Expand Up @@ -359,9 +374,9 @@ failure, journal and quota semantics LoopX already validates; keep B as the
cheaper replacement if the upstream interface appears; evaluate C only if
duplex streaming is required for the steward experience. Whichever option ships
must demonstrate, for one steward session, that the model work lands on the
operator credential and that no default path reaches an individual
subscription. This document authorizes no new scheduler, retry authority or
second monitoring subsystem to make that demonstration pass.
operator credential and that no default path of the steward channel reaches an
individual subscription. This document authorizes no new scheduler, retry
authority or second monitoring subsystem to make that demonstration pass.

Option A is the one that shipped, and its demonstration is a repository smoke
rather than a live transcript: `examples/loopx-steward-managed-chat-smoke.py`
Expand Down
39 changes: 25 additions & 14 deletions docs/architecture/rfcs/harness-selection-dsh-pi-v0.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,9 @@ C1、开销、保留与 Mode B 各行。

| 角色 | 来源 | 当前选型 | 晋级门槛 |
| --- | --- | --- | --- |
| 默认托管执行宿主 | LoopX Turn 加 `dsh` 宿主适配器,并绑定到运维方提供的模型端点 | 出货默认值:托管有界 Turn 走 `dsh`,与环境无关;`LOOPX_TURN_HOST` 可改指,显式 `--host` 优先;在托管栈中(PR #4443),尚未进入 `main` | 保持类型化 host request/result、独立验证与凭据归属运维方的边界;没有同等或更强的契约不替换 |
| 默认托管执行宿主 | LoopX Turn 加 `dsh` 宿主适配器,并绑定到运维方提供的模型端点 | 出货默认值:配置了运维方凭据时托管有界 Turn 走 `dsh`,没有凭据时走个体 `codex-cli`;显式 `LOOPX_TURN_HOST` 可改指,显式 `--host` 优先 | 保持类型化 host request/result、独立验证与凭据归属运维方的边界;没有同等或更强的契约不替换 |
| 管家通道执行器 | 管家回答所依赖的交互式 Chat 传输 | 出货默认值,按凭据分派:配置了 operator 凭据时为托管宿主(`dsh`),未配置时为 `codex`;`LOOPX_MANAGER_ENDPOINT` 可改指,显式端点优先;选型由 PR #4446 落地,条件默认值与单段传输随本次变更落地 | 单段传输的类型化边界(无流式、无跨 turn 宿主会话、沙箱只读)必须持续披露并可回读;任何托管通道都不得依赖个人订阅 |
| 受支持的替代 Turn 宿主 | LoopX Turn 加 `codex-cli` 适配器 | 可显式选择;它属于 `individual` 执行器类型,账落在某个人的 CLI 登录上 | 任何托管通道都不得静默依赖某个人的 CLI 订阅;个人通道必须被显式选择,而不是默认走到 |
| 受支持的替代 Turn 宿主 | LoopX Turn 加 `codex-cli` 适配器 | 可显式选择,也是上一行托管默认值在没有 operator 凭据的机器上的解析结果;它属于 `individual` 执行器类型,账落在某个人的 CLI 登录上 | 任何托管通道都不得*静默*依赖某个人的 CLI 订阅:个体宿主只会作为那条凭据解析默认值被走到,并以 `no_operator_credential` 回读,绝不被替换成运维方已选定的宿主 |
| L1 事件源与会话归属 runtime 候选 | DSH | opt-in,未晋级;有界 Turn 宿主角色见上一行默认值 | 本文 C0、C1、开销、保留与 Mode B 各行被真实执行并通过评审 |
| 可选的可见宿主循环 | Pi | 不是 managed runtime | 先声明按绑定持久化且可回读的会话模式,证明重启下的单执行器行为、"对话不是回执"、宿主本地状态非权威,并提供一条真实宿主重启行 |

Expand All @@ -63,12 +63,19 @@ DSH 绑定是 DSH Turn 宿主 + provider `deepseek-official` + 模型 `deepseek-
(DeepSeek V4.1 Flash)+ 推理档位 `high`,端点取自运维方环境(`DEEPSEEK_BASE_URL`),
凭据取自运维方环境(`DEEPSEEK_API_KEY`)。

LoopX **选择**托管有界 Turn 的默认宿主,而从不由环境推断
(`loopx/control_plane/turn_driver/host_binding.py`):出货默认值是 `dsh`,
`LOOPX_TURN_HOST` 可改指,显式 `--host` 优先于两者。operator 凭据不是选型输入。
这个区分正是该绑定的意义:发现一把 key 不等于决定换运行位置;一个按环境解析宿主的
面,会让"选定的配置"和"偶然生效的配置"无法区分。因此被选到 DSH 宿主的通道不会依赖
某个开发者本机 CLI 订阅是否可用、是否还有额度或是否已登录。
LoopX **选择**托管有界 Turn 的默认宿主,而从不由启动时的意外推断
(`loopx/control_plane/turn_driver/host_binding.py`):显式 `--host` 或
`LOOPX_TURN_HOST` 始终优先;两者都没配置时,出货默认值由运维方自己的凭据事实解析
——配置了凭据就是托管 `dsh` 宿主,没有凭据则是个体 `codex-cli` 宿主,因为无法认证的
托管宿主只会拒绝运行。真正需要区分的是**默认值**与**决定**:凭据可以解析一个本来
无从选择的默认值,但它永远不会改指运维方已经显式选定的宿主。因此解析到 DSH 宿主的
通道不会依赖某个开发者本机 CLI 订阅是否可用、是否还有额度或是否已登录;没有运维方
凭据的通道也不会悄悄借用别人的订阅。

本次变更同时改写了上表中"受支持的替代 Turn 宿主"的晋级门槛:它原文是"个人通道必须被
显式选择,而不是默认走到",而上面的凭据解析默认值与它冲突。改写后的规则保留原意——
任何通道都不得在运维方看不见的情况下依赖某个人的登录——并改为指明让这层依赖可见的
回读,而不是禁止这条已披露的默认值。

管家通道是**另一个**面;经下文记录的修订后,它的默认值用一条条件规则表达,而不是
一个宿主名:配置了 operator 凭据时通道选择托管宿主(`dsh`),未配置时为 `codex`。
Expand All @@ -86,13 +93,17 @@ LoopX **选择**托管有界 Turn 的默认宿主,而从不由环境推断
`DSH_MODEL`。回读是一行 `execution_profile`:出货形态为 `deepseek-v4-flash@high`,
仅当 provider 不是出货值时前置为 `<provider>/…`。之所以只有一行,是因为每个 plan
载荷都携带它,而面向 agent 的输出预算是一份契约;该行写出什么值,就是实际会跑的值,
因此 owner 自己设定的模型会以自身出现。凭据为选定档位提供认证,从不参与选型。
因此 owner 自己设定的模型会以自身出现。凭据为选定档位提供认证,从不参与选型;凭据
唯一解析的是"无人显式选择时有界 Turn 的出货宿主默认值",且该解析自带来源回读。

该绑定的证据按来源区分:

- 仓库覆盖、无需任何 provider 调用:出货默认值是 `dsh`,显式 `LOOPX_TURN_HOST`
可改指,显式 `--host` 仍然优先,且配置凭据不改变以上任何一项选择
(PR #4443 的测试,已进入 `main`);
- 仓库覆盖、无需任何 provider 调用:配置了运维方凭据时出货默认值是 `dsh`,没有时
是 `codex-cli`;显式 `LOOPX_TURN_HOST` 可改指任一默认值,显式 `--host` 优先于
全部(`tests/test_turn_default_host_binding.py`、
`tests/test_turn_managed_executor_binding.py`、
`examples/loopx-turn-managed-executor-binding-smoke.py`、
`examples/loopx-turn-managed-default-flow-smoke.py`);
- 本地真实验证:在真实 SDK 与 runtime(`deepseek-harness-sdk==0.1.5rc1`,即 PR
#4420 提出的固定版本;`main` 今天仍固定在 `0.1.2a3`,同一对路径在那里也通过)下,
进程内 `--host dsh` 路径与 `generic-cli` 子进程路径均通过;
Expand Down Expand Up @@ -291,8 +302,8 @@ dsh 片段**,把通道可见的有界历史与当前消息交给它,并返
选型规则:优先 A,因为它复用 LoopX 已经验证过的 Turn 权威、typed host failure、
journal 与配额语义;B 作为上游接口出现时的低成本替代;只有在管家体验确需双工
流式时才评估 C。无论采用哪条路线,都必须证明「一次管家会话的模型工作落在
operator 凭据上,且不存在任何默认指向个人订阅的路径」。本文件不授权为此新增
scheduler、重试权限或第二套监控子系统。
operator 凭据上,且管家通道自身不存在任何默认指向个人订阅的路径」。本文件不授权为此
新增 scheduler、重试权限或第二套监控子系统。

落地的是路线 A,其证明是一条仓库 smoke 而不是真实会话原文:
`examples/loopx-steward-managed-chat-smoke.py` 用真实内置 dsh 片段对接本地 mock 模型
Expand Down
12 changes: 7 additions & 5 deletions docs/integrations/deepseek-harness-connector.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,11 +141,13 @@ classification precedence, plus the hermetic verification smoke

## Host Selection And Managed Executor Readback

The Turn host is **selected, never inferred**. `dsh` is the shipped default
because it is the managed execution unit the steward drives; `LOOPX_TURN_HOST`
re-points that default, and an explicit `--host` (or `--host-adapter-command-json`)
wins over both. A configured `DEEPSEEK_API_KEY` only *authenticates* the selected
host: discovering a credential never changes where a Turn runs.
The Turn host is **selected, never inferred from an incidental environment**. An
explicit `--host` (or `--host-adapter-command-json`) or `LOOPX_TURN_HOST` always
wins. With neither configured, the shipped default is resolved from the
operator's own credential facts: `dsh` is the default when `DEEPSEEK_API_KEY` is
configured, because it is the managed execution unit the steward drives and that
credential authenticates it, and `codex-cli` is the default when no credential is
configured, because an unauthenticated managed host would refuse to run.

What runs on that host is a separate resolution. The managed execution profile
defaults to `deepseek-official` / `deepseek-v4-flash` / `high`, overridden by
Expand Down
7 changes: 5 additions & 2 deletions docs/reference/protocols/host-mode-plan-v0.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,8 +149,11 @@ quota guard command, and required proofs.
that this concrete host has already been resolved for the run; the runtime
resolves the concrete host from its own explicit product default
(`loopx/control_plane/turn_driver/host_binding.py`) when `plan_command` runs,
and `LOOPX_TURN_HOST` or an explicit `--host` re-points that default. An
operator credential authenticates the selected host; it does not select one.
and `LOOPX_TURN_HOST` or an explicit `--host` re-points that default. That
default is resolved from the operator credential, so this preview stays
deliberately credential-invariant: it pins no host and reports the resolution
as undone, instead of freezing one machine's credential facts into a plan that
other lanes read.
- `host_selection` is `resolved_default` when the command deliberately leaves
host resolution to `loopx turn plan`/`run-once`, and `pinned` when the command
carries an explicit `--host`.
Expand Down
Loading