Skip to content
12 changes: 12 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,18 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
- Replace the `global.forceDefaultOpsPtc` switch with one explicit action: the row's detail page carries a **Make OPS (PTC) the default** button that writes `selectedDefault: ops-ptc` once and answers `applied`/`no-update`/`unavailable`/`failed`. Apply, remount and unload no longer write the default, so a preset chosen on the settings page is not overridden on the next apply, and a saved `global.forceDefaultOpsPtc` key still loads with no effect.
- 用一次显式操作取代 `global.forceDefaultOpsPtc` 开关:行详情页有一个「设为 OPS (PTC) 默认」按钮,点一次写 `selectedDefault: ops-ptc`,并回报 `applied`/`no-update`/`unavailable`/`failed`。apply、重挂载与卸载都不再改写默认,设置页选定的预设不会在下一次 apply 被覆盖;已保存的 `global.forceDefaultOpsPtc` 键仍可加载但不再生效。

- The batching lesson no longer rides the accepted user batch: a user-role lesson enters logged history, where the model reads it as fresh input and answers the lesson instead of the task, feeding its own loop (#929). The one-time full lesson now rides the first accepted root `run_code` tool result through `additionalContexts` — the same-step ephemeral inbox the host never logs as user history — under contributor `batching-guidance:lesson`, distinct from the per-violation notices that keep the base id. The lesson latches at the delivery point inside the post-execute decision, so the previous `session/event` `user/message` latch, which waited for durable history that no longer happens, is gone.
- 批量教学不再挂在被接受的 user batch 上:user 角色的教学会进入 logged history,模型把它当新输入去回应教学本身而不是任务,形成自持循环(#929)。一次性完整教学现在随第一个被接受的根 `run_code` 工具结果走 `additionalContexts`——宿主从不记为 user history 的同一步 ephemeral 通道——contributor 为 `batching-guidance:lesson`,与保持原 id 的逐违规提示区分。教学在 post-execute 决策内的投递点就地置位,原先等待 durable history 的 `session/event` `user/message` latch 随该 history 不再发生而移除。

- The Niubash face list no longer names applets the frozen winuxcmd answers with "command not found" (measured: jq, link): a generated argv0 stub for those shadowed the system command with an entry that could not run it (#966). A prepared cache that still carries a face the list no longer declares is judged damaged and rebuilt from the pinned source, so a stale stub cannot survive a cache reuse.
- Niubash face 清单不再包含冻结 winuxcmd 以 "command not found" 回应的 applet(实测:jq、link):为它们生成的 argv0 桩会以一个无法运行的入口遮蔽系统命令(#966)。已 prepared 的缓存若仍携带清单不再声明的 face,会被判损坏并从固定源重建,旧桩无法在缓存复用中存活。

- Activation refuses an older host once, in one named diagnosis: a version below the package's own `engines.dsh` floor (`>=0.2.2-rc.1 <0.2.3-0`) fails `apply` at its first step with the floor, the host-reported version and the upgrade path, instead of loading halfway and dying in TypeError scope errors backstage with EXECUTOR_UNAVAILABLE in front (#701). An unreadable manifest or a version the host will not reveal cannot be proven below the floor, so both load as before; the range stays the single source of truth, read from the manifest beside the running build, never a copy.
- 激活期具名拒绝一次过旧宿主:低于本包自身 `engines.dsh` 下界(`>=0.2.2-rc.1 <0.2.3-0`)的版本让 `apply` 在第一步即失败,诊断给出下限、宿主实测版本与升级路径,而不是加载到一半在后场死于 TypeError scope 错误、前场只看到 EXECUTOR_UNAVAILABLE(#701)。清单不可读或宿主不肯报版本时无法证明低于下限,两者照旧加载;范围以清单为唯一事实源,从运行构建旁的 manifest 读取,绝不复制副本。

- A built-in preset session now answers `ops_status` about its own scope: the diagnosis tool was registered only behind an external preset row, while the diagnosis itself already understood mode sessions, so a session on a built-in preset had no named answer at all (#753). The built-in mode row mounts the same read-only diagnosis for exactly its own mode's sessions, and the mount settles asynchronously because a fiber that resolves synchronously never hears the `agent/created` dispatch the injection registered. Sessions of other modes stay unadmitted by that row, and the external preset row keeps ownership where it exists.
- 内置 preset 会话现在能对自身作用域应答 `ops_status`:诊断工具此前只随外部 preset 行注册,而诊断本身早已理解 mode 会话,落在内置 preset 上的会话完全没有具名答案(#753)。内置 mode 行为且仅为该 mode 的会话挂载同一只读诊断;挂载特意异步落定,因为同步 resolve 的 fiber 永远收不到注入里注册的 `agent/created` 派发。其他 mode 的会话仍不被该行接纳,外部 preset 行存在时继续保持其所有权。

## [0.5.5] — 2026-11-13 — Patch release

- A loader-less PTC scope no longer registers the configured `allowedTools` pool: with dynamic loading off nothing could ever select those APIs, and a host assembly without a step tool set declared all sixteen in `tools:sdk`. Resident publication, the default inspect + loader set and selection behavior are unchanged (#887).
Expand Down
4 changes: 4 additions & 0 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,10 @@ Long scripts, heredocs and multi-layer quotes and backslashes make the model esc

A key the `ops_bash` schema does not declare is refused before execution, and the error names both the unknown keys and the accepted ones. This is deliberate — nothing is silently ignored.

### The model calls `bash` instead of `ops_bash`

This package publishes exactly one shell tool, named `ops_bash`; there is no `bash` alias. The tool table is assembled by the host from the names this package declares once (`publicToolName` in `src/policy.ts`), and a misnamed call never reaches this package: the host answers with its own unknown-tool message, so any did-you-mean correction also belongs to the host, not here. Point the model back to the real name — the tool table and the prompt both spell `ops_bash` — instead of expecting a silent alias.

### Bash script files, PATH precedence and empty input

`script_path` always selects a Bash script; the extension does not select an
Expand Down
97 changes: 97 additions & 0 deletions src/adapter/dsh/host-floor.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
/**
* The host support boundary this package declares: engines.dsh in package.json
* names the floor, and activation time is where an older host must hear it (#701).
*
* A host below the floor used to load anyway and fail later - TypeError scope
* errors backstage, EXECUTOR_UNAVAILABLE in front. The host's own behaviour
* while loading an unsupported plugin remains upstream; what this package owns
* is refusing, at activation, in one named diagnosis. A version the host will
* not reveal can never be proven below the floor, so 'unknown' loads as before.
*/
import fs from 'node:fs'
import type { Context } from './types.js'
import { runtimeVersion } from './runtime-version.js'

/** One semver triple plus prerelease identifiers; build metadata never affects precedence. */
interface SemVer { major: number; minor: number; patch: number; pre: string[] }

const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+[0-9a-zA-Z-]+)?$/u
const NUMERIC = /^[0-9]+$/u

/** Parse one strict semver; anything else is not a version this check can judge. */
function parseSemVer(value: string): SemVer | undefined {
const match = SEMVER.exec(value)
if (match === null) return undefined
return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), pre: match[4] === undefined ? [] : match[4].split('.') }
}

/** Whether left sorts strictly before right under semver precedence rules. */
function precedes(left: SemVer, right: SemVer): boolean {
if (left.major !== right.major) return left.major < right.major
if (left.minor !== right.minor) return left.minor < right.minor
if (left.patch !== right.patch) return left.patch < right.patch
if (left.pre.length === 0) return false
if (right.pre.length === 0) return true
for (let index = 0; index < Math.max(left.pre.length, right.pre.length); index++) {
const a = left.pre[index], b = right.pre[index]
if (a === undefined) return true
if (b === undefined) return false
if (a === b) continue
if (NUMERIC.test(a) && NUMERIC.test(b)) return Number(a) < Number(b)
if (NUMERIC.test(a)) return true
if (NUMERIC.test(b)) return false
return a < b
}
return false
}

/**
* The floor this package declares for its host, from the first lower bound of
* engines.dsh; undefined when the manifest names no floor, which disables the check.
* The manifest is read once from the package root beside this module's own tree,
* so the declared range stays the single source of truth, never a copy.
* @returns the declared lower bound, or undefined.
*/
export function declaredHostFloor(): string | undefined {
if (cache === undefined) {
cache = null
try {
const manifest = JSON.parse(fs.readFileSync(new URL('../../../package.json', import.meta.url), 'utf8')) as { engines?: { dsh?: unknown } }
const range = manifest.engines?.dsh
if (typeof range === 'string') cache = range
} catch { /* An unreadable manifest disables the floor rather than guessing one. */ }
}
if (cache === null) return undefined
const floor = />=\s*(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/u.exec(cache)
return floor?.[1]
}

/** One read of the declared engines.dsh range; null marks "no floor declared". */
let cache: string | null | undefined

/**
* Whether an actual host version sorts strictly below the declared floor.
* @param {string} actual - the host-reported version.
* @param {string} floor - the declared lower bound.
* @returns {boolean} true only when both parse and actual sorts below floor.
*/
export function versionBelowFloor(actual: string, floor: string): boolean {
const left = parseSemVer(actual), right = parseSemVer(floor)
return left !== undefined && right !== undefined && precedes(left, right)
}

/**
* Refuse activation with one named diagnosis when the host is provably older
* than the declared floor; an unknown version is released, never punished.
* @param {Context} ctx - the host context the version probe reads.
* @returns {Promise<void>} resolves when the host is at or above the floor.
*/
export async function assertHostFloor(ctx: Context): Promise<void> {
const floor = declaredHostFloor()
if (floor === undefined) return
const { runtimeVersion: version } = await runtimeVersion(ctx)
if (version === 'unknown') return
if (versionBelowFloor(version, floor)) {
throw new Error(`This dsh-ops build requires DSH ${floor} or newer (package.json engines.dsh); the running host reports ${version}. Upgrade the host runtime instead of reloading this plugin: an older host loads it halfway at best, showing TypeError scope errors backstage and EXECUTOR_UNAVAILABLE in front.`)
}
}
13 changes: 11 additions & 2 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import { resolveModeConfig } from './presets/config.js'
import { resolveMergedConfig, effectiveMode, dynamicForMode } from './settings/merged.js'
import { MODE_IDS } from './presets/types.js'
import { beginMergedRow, endMergedRow } from './settings/legacy.js'
import { mountIntegration } from './integration/index.js'
import { mountIntegration, mountModeDiagnostics } from './integration/index.js'
import { gateConsumer } from './consumer/gates.js'
import { resolveIntegrationConfig } from './consumer/options.js'
import { mountRuntimeSettings } from './settings/runtime-host.js'
Expand All @@ -15,6 +15,7 @@ import * as tuiModule from './components/tui/index.js'
import * as downloadGuardModule from './components/download-guard/index.js'
import { configureResultCacheGc } from './kernel/result-cache-gc.js'
import { registerOpsPtcPreset } from './presets/ops-ptc/register.js'
import { assertHostFloor } from './adapter/dsh/host-floor.js'
export { Config } from './settings/merged.js'
export { applyComponent } from './legacy/host.js'
export const name = 'dsh-ops'
Expand All @@ -31,6 +32,11 @@ export const name = 'dsh-ops'

export async function apply(root: Context, rawConfig: unknown): Promise<void> {
const config = resolveMergedConfig(rawConfig)
// Activation-time host support boundary (#701): an older host hears one named
// diagnosis here instead of loading halfway and failing with TypeError scope
// errors backstage and EXECUTOR_UNAVAILABLE in front. An unknown host version
// cannot be proven below the floor, so it loads as before.
await assertHostFloor(root)
const host = root
const mount = async (module: { apply(...args: unknown[]): unknown }, state: { enabled: boolean; raw?: Record<string, unknown>; config: unknown }, slice?: Record<string, unknown>): Promise<void> => {
if (!state.enabled) return
Expand Down Expand Up @@ -59,10 +65,13 @@ export async function apply(root: Context, rawConfig: unknown): Promise<void> {
for (const mode of MODE_IDS) {
const state = config[mode]
const effective = resolveModeConfig(effectiveMode(state, config.global, typeof config.other.raw?.pwsh7Link === 'boolean' ? config.other.raw.pwsh7Link : companionVersion({ sweep: false }) !== undefined), mode)
await host.plugin({ name: `dsh-ops/consumer-${mode}`, apply(ctx: Context) {
await host.plugin({ name: `dsh-ops/consumer-${mode}`, async apply(ctx: Context) {
applyResolvedMode(ctx, effective, mode, { enabled: state.enabled,
discovery: { ...config.discovery.config, enabled: config.discovery.enabled },
dynamic: dynamicForMode(state, config.global) })
// Built-in modes answer ops_status too (#753): the named diagnosis used
// to exist only behind an external preset row.
await mountModeDiagnostics(ctx, mode)
} })
}
for (const row of Object.values(config.presets)) {
Expand Down
28 changes: 26 additions & 2 deletions src/integration/index.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
/** Stable opt-in preset entry. Consumers share the same assembler as built-in presets. */
import type { Context } from '../adapter/dsh/types.js'
import type { Agent, Context } from '../adapter/dsh/types.js'
import { mountConsumer } from '../consumer/mount.js'
import { replacementTargets } from '../consumer/replacements.js'
import { resolveIntegrationConfig, type IntegrationOptions, type IntegrationConfig } from '../consumer/options.js'
import { mountDiagnostics } from './diagnostics.js'
import { joinIntegration } from '../consumer/registry.js'
import { joinIntegration, integrationFor } from '../consumer/registry.js'
import { modeOf } from '../presets/detect.js'
import { onModesChange } from '../presets/registry.js'
import type { ModeId } from '../presets/types.js'
export { diagnose } from './diagnostics.js'
export type { Diagnostic } from './diagnostics.js'
export { registerNativeCapability } from '../discovery/providers.js'
Expand Down Expand Up @@ -33,6 +36,27 @@ export async function mountIntegration(ctx: Context, config: IntegrationConfig):
external: { allowed: config.externalTools, alwaysLoaded: config.externalAlwaysLoaded, disabled: config.externalDisabled },
})
}
/**
* One built-in mode publishes the same read-only diagnosis (#753): the status
* tool used to exist only behind an external preset row, so a built-in preset
* session could not see its own scope at all. The gate admits exactly the
* sessions of this mode without an external preset - the same row the mode's
* consumer is admitted by - so the two publications never overlap.
*
* The mount settles asynchronously on purpose: the listener this registers
* inside the tools injection has to be on a fiber that resolves after the
* synchronous apply returns, or the later `agent/created` dispatch never
* reaches it - the external preset row reaches the same point by awaiting its
* binding join, which is why only the built-in loop needed this one step.
*/
export async function mountModeDiagnostics(ctx: Context, mode: ModeId): Promise<void> {
await Promise.resolve()
mountDiagnostics(ctx, {
allows: (agent: Agent) => integrationFor(ctx, agent) === undefined && modeOf(ctx, agent) === mode,
watch: (notify: () => void) => onModesChange(ctx, notify),
})
}

/** Mount inside a preset composition or with an explicit preset id at the host root. */
export function integration(options: IntegrationOptions) {
const captured = structuredClone(options)
Expand Down
Loading
Loading