Skip to content
Closed
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
15 changes: 15 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,24 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
- The Bash tool description now states the parse contract of `stdout`/`stderr` where the model reads it: `text` may be a partial fragment, `truncated` marks one that must not be parsed as complete structured output, and `spillPath` is optional and not a completeness guarantee. The typed output schema is unchanged: repeating the contract there would cost every PTC request without saying anything the tool text does not. Command semantics, exit codes, result values, limits, spill files, permissions and rendering are unchanged.
- Bash 工具说明现在在模型读取它的地方写明 `stdout`/`stderr` 的解析契约:文本可能只是片段,`truncated` 标记的片段不得当作完整结构化输出解析,`spillPath` 是可选项且不保证完整。输出类型 schema 保持不变:在那里重复这段契约只会让每个 PTC 请求更贵,并不会多说明什么。命令语义、退出码、结果值、上限、落盘、权限与渲染均不变。

- A registered-but-unselected PTC pool API now answers a direct call with `SDK_NOT_LOADED` and a next action naming `ops_load_sdk` and its raw name, instead of `PUBLICATION_GRANT_UNAVAILABLE` (retry: never) on the file-lease path or a bare `POLICY_DENIED` on the PTC-only path. Hosts that render registered definitions can still declare the whole allowed pool, but the load flow now matches that declaration: the refusal says how to make the API callable (selection lands on the next model step) and stays honest when the current policy cannot load the API at all. Loader-less scopes keep registering nothing from the pool (#887 unchanged) (#968).
- 已注册但未选中的 PTC 候选池 API 被直接调用时,现在返回 `SDK_NOT_LOADED`,并在 nextAction 中点名 `ops_load_sdk` 与原始名称,不再在文件租约路径上返回 `PUBLICATION_GRANT_UNAVAILABLE`(retry: never)、在 PTC 专属路径上只返回光秃秃的 `POLICY_DENIED`。仍会渲染全部注册定义的宿主依旧可能声明整个 allowedTools 池,但加载流程与该声明现在一致:拒绝会说明如何让该 API 可调用(选择在下一模型步骤生效),且当前策略根本无法加载该 API 时保持诚实的通用拒绝。无 loader 作用域仍不注册池内任何项(#887 不变)(#968)。

- An unselected discovery capability, built-in or external provider, now answers a direct call with `CAPABILITY_NOT_SELECTED` and a next action naming `ops_discover_tools` with a `select:` query, instead of `PUBLICATION_GRANT_UNAVAILABLE` or a bare `POLICY_DENIED` that pointed nowhere. The pointer stays honest: a read-only scope that can never select a mutating capability keeps the generic refusal, and once a `select:` query has committed at step end the deferred rejection stops answering (#764).
- 未选中的发现能力(内置或外部 provider)被直接调用时,现在返回 `CAPABILITY_NOT_SELECTED`,并在 nextAction 中给出带 `select:` 查询的 `ops_discover_tools` 指引,不再返回无处可去的 `PUBLICATION_GRANT_UNAVAILABLE` 或光秃秃的 `POLICY_DENIED`。指引保持诚实:永远无法选中变更类能力的只读作用域仍返回通用拒绝;`select:` 查询在步骤结束提交后,延迟拒绝不再应答(#764)。

- Replacements fail open when the replacing executor cannot serve. A counterpart Bash call that settles with an unrecoverable preparation failure (`bash-runtime-missing`, `bash-ipc-mismatch`, `bash-lifecycle-lock-busy`, `bash-cache-unusable`, `bash-runtime-incompatible`) stops hiding the official tool from that agent's next model step, and a consumer whose Bash slot never resolved an executor keeps the official tools admitted even when a foreign same-name registration exists. Staging interruptions that the next call repairs keep the replacement in place. The lockout class of #962 — every official tool hidden behind a dead executor — is closed for these stages; a counterpart failure outside this vocabulary keeps the shadow, and the host-side rendering that ignores `when` remains upstream (#962).
- 替换在替换执行器无法服务时失效开放(fail-open):对应方 Bash 调用以不可恢复的准备失败(`bash-runtime-missing`、`bash-ipc-mismatch`、`bash-lifecycle-lock-busy`、`bash-cache-unusable`、`bash-runtime-incompatible`)结束时,该 agent 的下一模型步骤不再隐藏官方工具;Bash 槽位从未解析出执行器的消费者,即使存在同名外来注册也保持官方工具可入。下一次调用即可修复的 staging 中断不解除替换。#962 的锁死类——所有官方工具被一个死执行器挡住——对这些阶段已关闭;此词汇表之外的对应方失败仍保持影子,忽略 `when` 的宿主侧渲染仍属上游(#962)。

- The retained legacy file/shell row renders its tooling table from the calling scope's admitted view (`definitions` with the step tool set, falling back from `context.agent` to `context.scope`) instead of the root registration view. The host's `ctx.tools.get`/`definitions` reads ignore `when`, so a registered-but-unadmitted tool, for example a replacement shadow, could appear in the row's `read_image (host)` line while the step excluded it. The row now matches step admission; host-side sections that read registrations directly remain an upstream boundary outside this repository's control (#934).
- 保留的旧版 file/shell 行改为从调用作用域的已准入视图(带步骤 tool set 的 `definitions` 读取,并在 `context.agent` 缺席时回退 `context.scope`)渲染工具表,不再读取根注册视图。宿主的 `ctx.tools.get`/`definitions` 读取不检查 `when`,因此已注册但未准入的工具(例如替换影子)可能出现在该行的 `read_image (host)` 行里而步骤并不包含它。该行现在与步骤准入一致;直接读注册表的宿主侧提示词段落仍属上游边界,不在本仓控制范围(#934)。

- 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` 键仍可加载但不再生效。

- When no grant is entitled, the publication registrar consults every same-agent `deferred()` advisor in grant order instead of only the first one it finds. An advisor that answers `undefined` or throws no longer masks a later grant's pointer: one entry can hold several same-agent file leases — a PTC pool grant and a discovery pool grant for the same public name — and a host that ignores `when` used to get `PUBLICATION_GRANT_UNAVAILABLE` (retry: never) even though a later advisor could name `ops_load_sdk` or `ops_discover_tools`. The first advisor that answers wins; when none can help, the honest generic denial stays (#968 review finding).
- 无有资格 grant 时,发布 registrar 按插入顺序逐一咨询同 agent 的每个 `deferred()` advisor,不再只问找到的第一个。返回 `undefined` 或抛错的 advisor 不再遮蔽后续 grant 的指路:同一个注册项可同时持有多个同 agent 的文件租约——例如 PTC 候选池与发现池指向同一公开名——忽略 `when` 的宿主此前会拿到 `PUBLICATION_GRANT_UNAVAILABLE`(retry: never),即使后面的 advisor 本可点名 `ops_load_sdk` 或 `ops_discover_tools`。第一个给出答案的 advisor 胜出;全都无法指路时保持诚实的通用拒绝(#968 审核发现)。

## [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
6 changes: 5 additions & 1 deletion src/consumer/mount.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ export function mountConsumer(ctx: Context, plan: ConsumerPlan): void {
const { gate, core } = plan
let renderShellGuidance: (agent: Agent) => string = () => ''
const shellOwnsGuidance = (agent: Agent): boolean => Boolean(core.extraGuidance.trim()) && Boolean(renderShellGuidance(agent))
// A shell slot whose executor never resolved must never hide the official tools it was
// going to replace (#962): the replacement would advertise a counterpart that cannot run.
let bashUnavailable = false
if (plan.shell) {
// Host subprocess spills outlive the call that produced them upstream, so the
// row that publishes the shell also owns one bounded retention runtime.
Expand All @@ -31,6 +34,7 @@ export function mountConsumer(ctx: Context, plan: ConsumerPlan): void {
// Resolved once at mount: a slot whose executor never resolved publishes no tool at all, so the
// section below has to report that instead of rendering nothing for the whole session.
const bashResolution = shells.bash
bashUnavailable = !bashResolution.available
ctx.inject(['tools'], inner => mountSessionBash(inner, core, shells, gate))
if (core.promptPolicy) ctx.inject(['tools', 'systemPrompt'], inner => {
mountJobWaitGuidance(inner, plan.id, gate)
Expand Down Expand Up @@ -61,5 +65,5 @@ export function mountConsumer(ctx: Context, plan: ConsumerPlan): void {
extraGuidanceOwner: agent => shellOwnsGuidance(agent) || nativeOwnsGuidance(agent),
residentTools: () => residents.map(publicToolName), external: plan.external })
} else if (plan.files) mountPtc(ctx, plan.ptc, { ...gate, guidance: core.promptPolicy, resident: plan.residentTools, dynamic: plan.discovery })
if (plan.replaceOfficial) mountReplacements(ctx, { id: plan.id, targets: plan.replacementTargets, gate, keepOfficial: () => false })
if (plan.replaceOfficial) mountReplacements(ctx, { id: plan.id, targets: plan.replacementTargets, gate, keepOfficial: () => bashUnavailable })
}
22 changes: 22 additions & 0 deletions src/discovery/controller.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import { activationIsPtc, isNativePresentation, isPresentationProbe } from '../p
import { visibleNames } from '../publication/surface.js'
import { mountResultLifecycle } from '../kernel/result-lifecycle.js'
import { failure, resolveWorker } from '../execution/files.js'
import type { Outcome } from '../kernel/outcome.js'
import { capability, DISCOVERY_TOOL_NAME } from '../capabilities/registry.js'
import { DISCOVERY_DESCRIPTION, DISCOVERY_PARAMETERS, DISCOVERY_OUTPUT } from '../capabilities/discovery.js'
import { publicToolName, renderToolingPolicy } from '../policy.js'
Expand Down Expand Up @@ -93,6 +94,23 @@ export function mountDiscovery(root: Context, raw: unknown, gate: DiscoveryGate)
const api = apiByName.get(name)
return api !== undefined && selectable(agent, api) && (config.alwaysLoaded.includes(api) || entry.selected.has(api))
}
/** Point a declared-but-unselected capability at the selector; undefined when discovery cannot select it (#764). */
const deferredRejection = (agent: Agent, entry: Entry, name: string, provider?: Provider): Outcome<never> | undefined => {
if (!selected(agent, entry, DISCOVER)) return undefined
if (provider !== undefined) {
if (!externalPool(agent).includes(provider) || !externalAvailable(provider, agent)
|| gate.external?.alwaysLoaded.includes(name) || provider.capability.disclosure === 'resident'
|| entry.externalSelected.has(provider.token)) return undefined
} else {
const api = apiByName.get(name)
if (api === undefined || !selectable(agent, api) || config.alwaysLoaded.includes(api) || entry.selected.has(api)) return undefined
}
return { status: 'error', error: {
code: 'CAPABILITY_NOT_SELECTED', effectState: 'none', retry: 'never',
message: `Capability '${name}' is discoverable for this scope but is not selected yet; no action was executed.`,
nextAction: `Call ${DISCOVER} with a select: query naming it (for example query: "select:${name}"); the tool becomes available on the next model step.`,
} }
}
const rotateFiles = (agent: Agent, entry: Entry): void => {
for (const [api, file] of entry.files) {
const entitled = selected(agent, entry, publicToolName(api))
Expand All @@ -103,6 +121,7 @@ export function mountDiscovery(root: Context, raw: unknown, gate: DiscoveryGate)
dispatch: async () => undefined,
present: async activation => activation.agent === agent && entries.get(agent) === entry
&& permitted(agent, api) && !await activationIsPtc(prompt, activation),
deferred: () => deferredRejection(agent, entry, publicToolName(api)),
})
file.entitled = entitled
}
Expand All @@ -113,6 +132,9 @@ export function mountDiscovery(root: Context, raw: unknown, gate: DiscoveryGate)
const current = () => !exec.signal.aborted && entries.get(agent) === entry && exec.agent === agent
&& selected(agent, entry, source.name, provider) && tools.executable(source.name, agent, exec.toolSet) === definition
if (!current() || !await isNativePresentation(prompt, agent, exec.signal).catch(() => false) || !current()) {
// A registered-but-unselected capability points at the selector; every other admission failure keeps the generic refusal.
const deferred = deferredRejection(agent, entry, source.name, provider)
if (deferred !== undefined) return deferred
return failure('POLICY_DENIED', 'This Native capability must be admitted for the calling scope; no action executed.')
}
if (!provider) return source.execute(args, exec)
Expand Down
11 changes: 7 additions & 4 deletions src/legacy/host.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
/** Retained pre-single-row component behavior; never part of the current composition root. */
import type { Context } from '../adapter/dsh/types.js'
import type { Agent } from '../adapter/dsh/types.js'
import type { ResolvedToolSet } from '../adapter/dsh/types.js'
import type {} from '../adapter/dsh/types.js'
import type {} from '../adapter/dsh/types.js'
import { resolveConfig } from '../config.js'
Expand Down Expand Up @@ -31,13 +32,15 @@ function report(ctx: Context, message: string, level = 'error'): void {
else if (level === 'warn') console.warn(message)
else console.error(message)
}
function visibleTools(ctx: Context, agent?: Agent): string[] {
function visibleTools(ctx: Context, agent?: Agent, toolSet?: ResolvedToolSet): string[] {
try {
const tools = ctx.get('tools')
// Names only, through the view: `schemas()` projected every visible definition —
// 34.2 ms for 258 tools at the published runtime's surface shape — to keep a
// handful of owned names, and this section renders once per assembly.
return tools ? visibleNames(tools, agent) : []
// handful of owned names, and this section renders once per assembly. The toolSet
// read is the honest one: a host that ignores `when` in its definition reads would
// otherwise advertise a registered-but-unadmitted tool the step excludes (#934).
return tools ? visibleNames(tools, agent, toolSet) : []
} catch { return [] }
}

Expand Down Expand Up @@ -119,7 +122,7 @@ export function applyComponent(root: Context, rawConfig: unknown, component: Com
order: SECTION_ORDERS[TOOLING_SECTION] + (component === 'shell' ? 1 : 0),
interpolate: false,
text: context => renderToolingPolicy({
published: visibleTools(ctx, context.agent).filter(name => owned.includes(name)),
published: visibleTools(ctx, context.agent ?? context.scope as Agent, context.toolSet).filter(name => owned.includes(name)),
shellComponent: component === 'shell',
extraGuidance: config.extraGuidance,
}),
Expand Down
14 changes: 14 additions & 0 deletions src/publication/ptc.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ import { InvocationLifetime, InvocationNotStarted } from '../lifecycle/invocatio
import { monitoredInvoke } from '../execution/monitored.js'
import { record } from '../execution/boundary.js'
import { failure, resolveWorker } from '../execution/jobs.js'
import type { Outcome } from '../kernel/outcome.js'
import { WORKER_TIMEOUT_MS } from '../execution/protocol.js'
import { registerStepTailProvider } from '../prompt-injection/index.js'
import { mountWorkspacePreparation } from '../workspace-preparation.js'
Expand Down Expand Up @@ -108,6 +109,15 @@ export function mountPtc(root: Context, rawConfig: unknown, gate: PtcGate = { al
})
}

/** Point a declared-but-unselected pool API at the loader; undefined when loading cannot help (#968). */
const deferredRejection = (entry: Entry, api: ApiName): Outcome<never> | undefined => {
if (gate.dynamic === false || !loadable.includes(api) || !permitted(entry.agent, api) || selected(entry, api)) return undefined
return { status: 'error', error: {
code: 'SDK_NOT_LOADED', effectState: 'none', retry: 'never',
message: `API '${api}' is in this scope's allowed pool but is not loaded into the typed SDK yet; no action was executed.`,
nextAction: `Call ${publicToolName('load_sdk')} with tools:["${api}"] and use the API on the next model step; retrying this call without loading fails the same way.`,
} }
}
const execute = (entry: Entry, api: ApiName | 'load_sdk'): ToolDefinition['execute'] => async (args, exec) => {
// The public assembly may finish after its executor sections changed.
// Refuse that stale verdict rather than dispatching under the old text.
Expand All @@ -116,6 +126,9 @@ export function mountPtc(root: Context, rawConfig: unknown, gate: PtcGate = { al
&& revision === presentationRevision && permitted(entry.agent, api) && selected(entry, api)
&& (capability(api)?.component === 'file' || tools.executable(publicToolName(api), entry.agent, exec.toolSet) === entry.definitions.get(publicToolName(api)))
if (!current() || !await isPtc(entry.agent, exec.signal).catch(() => false) || !current()) {
// A declared-but-unselected pool API points at the loader; every other admission failure keeps the generic refusal.
const deferred = api === 'load_sdk' ? undefined : deferredRejection(entry, api)
if (deferred !== undefined) return deferred
return failure('POLICY_DENIED', 'This API must be admitted for the calling PTC scope; no action executed.')
}
if (api === 'load_sdk') {
Expand Down Expand Up @@ -147,6 +160,7 @@ export function mountPtc(root: Context, rawConfig: unknown, gate: PtcGate = { al
present: activation => activation.agent === entry.agent && permitted(entry.agent, api)
&& selected(entry, api) && activationIsPtc(prompt, activation),
dispatch: file.dispatch,
deferred: () => deferredRejection(entry, api),
})
file.granted = { entitled, selected: selection, config }
}
Expand Down
Loading
Loading