@danceiny/gotry 0.0.1-rc.15 → 0.0.1-rc.17

package/ts/src/index.ts

@@ -7,7 +7,7 @@
  *   - gotry_wish_pool_add       「下一次出发」清单(憧憬不被拒绝)
  *
  * 插件形态遵循 dsh 约定(name/inject/Config/apply + ctx.tools.register(defineTool(...))),
- * 对齐已发布 @deepseek-ai/dsh-tools@0.0.1-rc.1 的契约:
+ * 对齐 @deepseek-ai/dsh-tools@0.1.2-alpha.3 的契约:
  * render 位于 output 对象内,参数属性是 ValueSchemaSpec(支持 type:'json')。
  *
  * @module @gotry/plugin
@@ -35,11 +35,38 @@ import { anythingSearch } from '../capabilities/anything.ts'
 import { readUrl, reach, reachStatus } from '../capabilities/agent-reach.ts'
 import { videoSubtitle, githubSearch } from '../capabilities/agent-reach-deep.ts'
 import { sessionLogin } from '../capabilities/session-login.ts'
+import { EXTENSION_STORE_URL } from '../capabilities/session/extension-bridge.ts'
 import { createConsentGate, approvalFromContext } from '../capabilities/session-consent.ts'
+import { installModelOverride } from '../capabilities/model-override.ts'
 import { listArtifacts, readArtifact } from '../capabilities/artifacts.ts'
 import { interpretEffect, declinedObservation } from '../capabilities/effect.ts'
+import { appendFacts, loadFactRegistry } from '../capabilities/fact-log.ts'
+import { factsFromFlyai, factsFromSession } from './bookable-facts.ts'
+import { gateArtifact, type AirlineAirportMap } from './artifact-gate.ts'
+import { installToolBudget } from './tool-budget.ts'
+import { registerBenchmarkEnvironmentBridge, type BenchmarkSubprocessService } from './benchmark-environment-bridge.ts'
+import { installBenchmarkToolIsolation } from './benchmark-tool-isolation.ts'
+import { installBenchmarkAgentConformance } from './benchmark-agent-conformance.ts'
+
+/** 航司→机场映射表(issue #46 冲突检测面;data/airline-airports.json,as_of 快照) */
+let airlineAirportMapCache: AirlineAirportMap | null = null
+async function loadAirlineAirportMap(): Promise<AirlineAirportMap | null> {
+  if (airlineAirportMapCache) return airlineAirportMapCache
+  try {
+    const { readFile } = await import('node:fs/promises')
+    airlineAirportMapCache = JSON.parse(
+      await readFile(join(import.meta.dirname, '..', '..', 'data', 'airline-airports.json'), 'utf-8'),
+    ) as AirlineAirportMap
+    return airlineAirportMapCache
+  } catch {
+    return null // 映射缺失不阻塞检索主路径;闸工具侧另行显式报错
+  }
+}
 
 export const name = 'gotry-tools'
+// The bridge obtains subprocess through an optional Cordis lookup at apply
+// time. Declaring it as a required injection would make the whole plugin
+// depend on a service that is only needed for explicit benchmark opt-in.
 export const inject = ['tools', 'systemPrompt']
 
 export interface Config {
@@ -51,6 +78,8 @@ export interface Config {
   hbcliBin: string
   /** 账号会话检索总闸(RFC 支柱④「用户明示授权+随时可关」):ask=gotry_session_search 每会话每站点首次调用弹审批卡、会话内记住(默认);allow=用户已在配置明示预授权(直接放行);off=总闸关闭,直接拒绝 */
   sessionAccess: string
+  /** Owner-local benchmark environment bridge config; empty disables the bridge. */
+  benchmarkEnvironmentConfigPath?: string
 }
 
 export const Config: z<Config> = z.object({
@@ -58,6 +87,7 @@ export const Config: z<Config> = z.object({
   timeoutMs: z.number().default(30_000),
   hbcliBin: z.string().default('hbcli'),
   sessionAccess: z.string().default('ask'),
+  benchmarkEnvironmentConfigPath: z.string().default(''),
 })
 
 interface FeasibilityResult {
@@ -134,6 +164,29 @@ type Json = string | number | boolean | null | Json[] | { [k: string]: Json }
 type JsonObject = { [k: string]: Json }
 
 export function apply(ctx: Context, config: Config): void {
+  installToolBudget(ctx)
+
+  const rawBenchmarkEnvironmentConfigPath = config.benchmarkEnvironmentConfigPath ?? ''
+  if (rawBenchmarkEnvironmentConfigPath.trim()) {
+    // Benchmark mode is a deliberately minimal kernel: only the model
+    // override and the environment bridge are installed.  In particular,
+    // product prompt variables, process/consent guards, and guarded product
+    // tools must not be observable on this path.
+    installModelOverride(ctx as unknown as Parameters<typeof installModelOverride>[0])
+    const getService = (ctx as unknown as { get?: (name: string, fallback?: unknown) => unknown }).get
+    const directSubprocess = (typeof getService === 'function'
+      ? getService.call(ctx, 'subprocess')
+      : undefined) as BenchmarkSubprocessService | undefined
+    const projection = registerBenchmarkEnvironmentBridge(
+      rawBenchmarkEnvironmentConfigPath,
+      tool => ctx.tools.register(tool),
+      directSubprocess,
+    )
+    installBenchmarkToolIsolation(ctx)
+    installBenchmarkAgentConformance(ctx, projection)
+    return
+  }
+
   // 时间感知:注册动态变量,persona 里用 {{current_date}} 引用。
   // 每次 assemble 时取系统时钟——LLM 始终知道「今天是几号」。
   const sp = (ctx as unknown as Record<string, unknown>)['systemPrompt'] as {
@@ -175,6 +228,10 @@ export function apply(ctx: Context, config: Config): void {
     }))
   }
 
+  // LLM_MODEL → dsh 会话面模型覆盖(issue #77;机制与分层见
+  // capabilities/model-override.ts 头注)。GOTRY_LLM_MODEL 未设时零行为变化。
+  installModelOverride(ctx as unknown as Parameters<typeof installModelOverride>[0])
+
   // D-NEW 收尾:全部工具 execute 统一异常隔离——单个工具抛错/拒绝不再沿 cordis
   // 传到 dsh 主循环,降级为结构化错误返回给 LLM + incident 落盘(incident-log.ts)。
   const registerGuarded = (tool: ReturnType<typeof defineTool>): void => {
@@ -737,6 +794,10 @@ export function apply(ctx: Context, config: Config): void {
       const itp = await interpretEffect({ effect: 'FLYAI_SEARCH', params: { kind, origin: q.from, destination: q.to, depDate: q.date } })
       if (!itp.result) return declinedObservation('FLYAI_SEARCH', itp.trace)
       const r = itp.result
+      // issue #46 事实落账(ADR-19):exact-date 检索结论(hit 正事实 / miss 负事实)追加进
+      // bookable-facts 侧车——产物事实闸(gotry_fact_gate)的唯一事实源;落盘失败不阻塞检索
+      const avMap = await loadAirlineAirportMap()
+      await appendFacts(config.stateRoot ?? '.', factsFromFlyai({ kind, origin: q.from, destination: q.to, date: q.date }, r, new Date().toISOString(), avMap?.city_alias))
       const top = (r.options ?? []).slice(0, 8).map(o => `${o.no} ${o.name} ${o.depDateTime.slice(11, 16)}→${o.arrDateTime.slice(11, 16)} ¥${o.price}`)
       // issue #24:miss(上游正常返回 0 条)与 error(限流/网络)分开陈述,不再混写「无结果或失败」
       // (过去日期已被上方预校验拦下,此处不会出现过期查询)
@@ -761,9 +822,10 @@ export function apply(ctx: Context, config: Config): void {
     name: 'gotry_session_login',
     description:
       'Productized login bootstrap for the account session channel (call this when gotry_session_search returns needs-login — the user never needs a terminal). ' + 'AUTO-DETECTION FIRST: it reads ticket-cookie NAMES before anything else — if the user already logged in (on the external site) it confirms instantly WITHOUT opening any page. '
-      + 'OPENS the site login entry in the USER\'S OWN Chrome and waits for the user to finish logging in on the external site. '
+      + 'OPENS the site login entry in the USER\'S OWN Chrome (foreground tab, left open for the user) and waits for the user to finish logging in on the external site. '
       + 'GoTry NEVER collects, stores, or transmits credentials: no passwords, no SMS codes, no cookie values — it only checks the boolean fact "already logged in" (reads cookie NAMES only, zero values). '
-      + 'verdict logged-in (tickets detected) | pending (login tab opened, user not done yet — offer to re-check later) | needs-attach (one-time Chrome remote-debugging switch instructions). '
+      + 'Transport: the GoTry Session Bridge browser extension (one-time install, ZERO Chrome system dialogs). '
+      + `verdict logged-in (tickets detected) | pending (login tab opened, user not done yet — offer to re-check later) | needs-extension (one-time extension install: the verdict surfaces the Chrome Web Store installUrl as a clickable link for dsh UI to render — installation is a browser concern, not gotry's). `
       + 'Evidence [会话:<site>-login@ts].',
     parameters: {
       query: { type: 'json', required: true, description: '可空对象 {}: { waitSeconds?: number }(等待用户完成登录的上限秒数,默认 90,至多 300)' },
@@ -776,16 +838,29 @@ export function apply(ctx: Context, config: Config): void {
         ? `${r.site} 登录完成确认(票据 cookie 名已检出,只读名字)。说明:登录是在携程官网、用你自己的浏览器完成的——gotry 全程未接触任何密码/验证码/cookie 值。现在可以继续会话检索了。${r.evidence}`
         : r.verdict === 'pending'
           ? `登录入口已在你的 Chrome 打开;请在弹出的标签页里正常登录携程(登录由你在官网完成,不属于 gotry)。完成后说一声"继续",我再确认。gotry 只检查"是否已登录",永不收集你的账号信息。${r.evidence}`
-          : r.verdict === 'needs-attach'
-            ? `需要一次性开启你 Chrome 的远程调试开关:在你的 Chrome 地址栏打开 chrome://inspect/#remote-debugging 并打开开关,然后说一声"重试"。${r.evidence}`
-            : `登录引导未完成:${r.error ?? '未知原因'} ${r.evidence}`
+          : r.verdict === 'needs-extension'
+            ? `需要一次性安装 GoTry Session Bridge 浏览器扩展:这是浏览器的事,gotry 不弹面板不开剪贴板——请直接在 Chrome 应用商店一键装(add-to-chrome 自动更新)。storeUrl=${EXTENSION_STORE_URL}. 装好即生效,装完后告诉我「重试」即可。${r.evidence}`
+            : r.verdict === 'needs-attach'
+              ? `cdp 车道需要一次性开启你 Chrome 的远程调试开关:在你的 Chrome 地址栏打开 chrome://inspect/#remote-debugging 并打开开关,然后说一声"重试"(默认走扩展车道,无需此步)。${r.evidence}`
+              : `登录引导未完成:${r.error ?? '未知原因'} ${r.evidence}`
       return JSON.parse(JSON.stringify({ ...r, summary })) as Record<string, never>
     },
     presentCall: _args => ({ card: 'generic', title: '登录携程(用你自己的浏览器,不在 gotry 输入)', kind: 'fetch', rawInput: {} }),
     presentResult: (_args, value) => {
-      const r = value as { verdict?: string; tickets?: string[] }
-      const label = r.verdict === 'logged-in' ? `已登录(${(r.tickets ?? []).length} 票据)` : r.verdict === 'pending' ? '等待你在携程页面完成登录' : r.verdict ?? '降级'
-      return { card: 'generic', title: `账号登录:${label}`, content: [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }] }
+      const r = value as { verdict?: string; tickets?: string[]; installUrl?: string }
+      const needsExt = r.verdict === 'needs-extension'
+      const label = r.verdict === 'logged-in'
+        ? `已登录(${(r.tickets ?? []).length} 票据)`
+        : r.verdict === 'pending'
+          ? '等待你在携程页面完成登录'
+          : needsExt
+            ? '🧩 需装 GoTry Session Bridge 扩展(浏览器商店一键装,自动更新)'
+            : r.verdict ?? '降级'
+      const content: Array<{ type: 'text'; text: string }> = [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }]
+      // needs-extension:把商店 URL 渲成可点链接(浏览器自己当安装器,gotry 不插手)
+      // dsh presentResult 若支持 actions 字段,URL 可被原生渲染;否则 content 里也保留文本兜底
+      if (needsExt && r.installUrl) content.push({ type: 'text', text: `安装链接:${r.installUrl}` })
+      return { card: 'generic', title: `账号登录:${label}`, content }
     },
   }))
 
@@ -794,9 +869,10 @@ export function apply(ctx: Context, config: Config): void {
     description:
       'Search on the USER\'S OWN logged-in browser session (Ctrip flights today; the account channel, not an anonymous instance). '
       + 'Consent gate: the FIRST call in a session asks the user via the runtime approval card; once granted it holds for the session, a refusal revokes it for the session (no repeat prompting). '
-      + 'ReadGuard = physically read-only (write requests aborted at network layer; agent NEVER touches credentials/captcha; on captcha it stops and returns challenged). '
+      + 'Transport: GoTry Session Bridge browser extension (one-time install) — the agent side never talks to Chrome debugging, ZERO system dialogs; read-only by construction (the extension never issues requests; it only passively forwards the site\'s own search responses; agent NEVER touches credentials/captcha; on captcha it stops and returns challenged). '
       + 'Currently ctrip-flight: sniffs the site search API for structured options. Evidence [会话:ctrip-flight@ts]. '
-      + 'verdict needs-login = call gotry_session_login (product tool: opens the Ctrip login entry in the user\'s own Chrome and waits for them to log in on the external site — no terminal, no credentials through GoTry); needs-attach = one-time Chrome remote-debugging switch. '
+      + 'verdict needs-login = call gotry_session_login (opens the Ctrip login entry in the user\'s own foreground tab — no terminal, no credentials through GoTry); '
+      + `needs-extension = one-time browser-extension install (Chrome Web Store one-click, installUrl is also surfaced as a clickable link in the verdict field for dsh UI to render) — the DEFAULT transport; cdp (chrome://inspect remote debugging) is a diagnostic fallback only via GOTRY_SESSION_TRANSPORT=cdp. `
       + 'Rate-limited (≥30s between same-site calls; a challenged/timeout verdict means STOP — never retry, fall back to other tools).',
     parameters: {
       query: { type: 'json', required: true, description: '{ from: "上海", to: "丽江", date: "2026-10-01" }' },
@@ -819,6 +895,9 @@ export function apply(ctx: Context, config: Config): void {
       })
       if (!itp.result) return declinedObservation('SESSION_FLIGHT_SEARCH', itp.trace)
       const r = itp.result
+      // issue #46 事实落账(ADR-19):会话面 exact-date 结论同样进事实注册表(独立 source 并列标注)
+      const avMapS = await loadAirlineAirportMap()
+      await appendFacts(config.stateRoot ?? '.', factsFromSession({ origin: q.from, destination: q.to, date: q.date }, r, new Date().toISOString(), avMapS?.city_alias))
       const top = (r.options ?? []).slice(0, 8).map(o => `${o.flightNo} ${o.airline} ${o.depDateTime.slice(11, 16)}→${o.arrDateTime.slice(11, 16)} ¥${o.price}`)
       const summary = r.verdict === 'hit'
         ? `${q.from}→${q.to} ${q.date} 会话检索(携程,用户本人登录态)前 ${top.length} 条:\n${top.join('\n')}\n${r.evidence}`
@@ -827,9 +906,18 @@ export function apply(ctx: Context, config: Config): void {
     },
     presentCall: args => ({ card: 'generic', title: `会话检索:${String((args.query as { from?: string })?.from ?? '')}`, kind: 'fetch', rawInput: args.query }),
     presentResult: (_args, value) => {
-      const r = value as { verdict?: string; options?: unknown[] }
-      const label = r.verdict === 'hit' ? `会话 ${r.options!.length} 条` : (r.verdict === 'needs-login' ? '需登录' : r.verdict ?? '降级')
-      return { card: 'generic', title: `会话检索:${label}`, content: [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }] }
+      const r = value as { verdict?: string; options?: unknown[]; installUrl?: string }
+      const needsExt = r.verdict === 'needs-extension'
+      const label = r.verdict === 'hit'
+        ? `会话 ${r.options!.length} 条`
+        : r.verdict === 'needs-login'
+          ? '需登录'
+          : needsExt
+            ? '🧩 需装 GoTry Session Bridge 扩展(浏览器商店一键装,自动更新)'
+            : r.verdict ?? '降级'
+      const content: Array<{ type: 'text'; text: string }> = [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }]
+      if (needsExt && r.installUrl) content.push({ type: 'text', text: `安装链接:${r.installUrl}` })
+      return { card: 'generic', title: `会话检索:${label}`, content }
     },
   }))
 
@@ -1181,4 +1269,63 @@ export function apply(ctx: Context, config: Config): void {
       }
     },
   }))
+
+  // ---- 产物事实闸(issue #46,ADR-19):含可下单事实的产物交付前必过 ----
+  // 每个航班号/时刻/机场/价格/政策断言必须回溯到本会话 exact-date 工具结果
+  // (bookable-facts 侧车,query_id 可重放);无法回溯即 blocked——不得宣称「已验证方案」。
+
+  registerGuarded(defineTool({
+    name: 'gotry_fact_gate',
+    description:
+      'Factuality gate for itinerary artifacts (issue #46): call BEFORE delivering any artifact that contains bookable facts '
+      + '(flight numbers, times, airports, prices, visa/entry policies). Every bookable claim in the markdown is checked against '
+      + 'the session fact registry (exact-date tool results recorded by gotry_flyai_search / gotry_session_search — hit AND miss). '
+      + 'Blocked when: a claimed flight is absent from the exact-date source (never backfill from route pages/history/adjacent dates); '
+      + 'route+date never queried; times contradict the snapshot; carrier→airport mapping conflicts (FD=DMK vs VZ=BKK are NOT interchangeable); '
+      + '「联程」without protected_connection=true; policy claims without 「截至 YYYY-MM-DD」; unconditional ✓ on unverified claims. '
+      + 'Optional itinerary object enables machine invariants (hotel_nights + onboard_nights = total nights, O&D segments vs flight legs, '
+      + 'budget floor ≥ sum of item minimums). verdict=blocked ⇒ fix or downgrade wording — never present as a verified plan.',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ markdown?: "<产物全文>", path?: "<产物路径(artifacts_list 返回的)>— 二选一", tripYear?: 2027, itinerary?: { trip_start, trip_end, stays: [{place,check_in,check_out}], onboard_nights, od_segments: [{from,to,date,mode,legs}], budget_items: [{label,min_cny,max_cny}], claimed_floor_cny? } }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? JSON.stringify(value).slice(0, 800)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ markdown?: string; path?: string; tripYear?: number; itinerary?: Record<string, unknown> }>(args, 'markdown')
+      const avMap = await loadAirlineAirportMap()
+      if (!avMap) {
+        return JSON.parse(JSON.stringify({ ok: false, summary: '航司机场映射缺失(data/airline-airports.json)——事实闸不可用,fail closed:产物不得宣称已验证' })) as Record<string, never>
+      }
+      let markdown = q.markdown
+      if (!markdown && q.path) {
+        const r = await readArtifact({ stateRoot: config.stateRoot ?? '.', path: q.path })
+        if (!r.ok) return JSON.parse(JSON.stringify({ ok: false, summary: `产物读取失败:${String((r as { error?: string }).error ?? '')}` })) as Record<string, never>
+        markdown = r.content
+      }
+      if (!markdown) return JSON.parse(JSON.stringify({ ok: false, summary: '需要 markdown(产物全文)或 path(产物路径)' })) as Record<string, never>
+      const itinerary = q.itinerary as import('./bookable-facts.ts').ItineraryFacts | undefined
+      const registry = await loadFactRegistry(config.stateRoot ?? '.')
+      const report = gateArtifact(markdown, registry, avMap, { trip_year: q.tripYear, itinerary })
+      const lines = report.violations.slice(0, 20).map(v => `  L${v.line} [${v.kind}] ${v.detail}`)
+      const summary = report.verdict === 'pass'
+        ? `事实闸 PASS:${report.traceable}/${report.claims_checked} 可下单 claim 全部回溯到 exact-date 工具结果(query_id 可重放)——可宣称「已验证方案」。`
+        : `事实闸 BLOCKED(${report.violations.length} 违例,${report.traceable}/${report.claims_checked} claim 可回溯)——不得宣称「已验证方案」:\n${lines.join('\n')}\n修正路径:逐条改成 exact-date 源返回的事实,或降级为「未确认/当前不可售,到 D-xx 复核」;exact-date miss 的 route+date 不得用历史班期/相邻日期/航线页填充。`
+      return JSON.parse(JSON.stringify({ ok: true, ...report, summary })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: '产物事实闸', kind: 'execute', rawInput: args.query }),
+    presentResult: (_args, value) => {
+      const r = value as { verdict?: string; violations?: unknown[]; summary?: string }
+      return {
+        card: 'generic',
+        title: `事实闸:${r.verdict === 'pass' ? '✅ pass' : `⛔ blocked(${r.violations?.length ?? '?'})`}`,
+        content: [{ type: 'text', text: String(r.summary ?? '') }],
+      }
+    },
+  }))
 }

package/ts/src/state-ledger.ts

@@ -681,6 +681,7 @@ export class StateLedger {
 
   close(): void {
     this.db.close()
+    for (const [key, value] of openLedgers) if (value === this) openLedgers.delete(key)
   }
 }
 

package/ts/src/tool-budget.ts

@@ -0,0 +1,165 @@
+/** Per-agent, per-turn guard for model-driven tool loops. */
+
+import { randomUUID } from 'node:crypto'
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { ToolExecutionResult, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
+
+export const TOOL_BUDGET_SOFT_CALL = 16
+export const TOOL_BUDGET_HARD_CALL = 18
+export const TOOL_BUDGET_EXHAUSTED = 'TOOL_BUDGET_EXHAUSTED'
+
+export type ToolBudgetDecision =
+  | { kind: 'allow'; softSignal: boolean; exhaustsBudget: boolean }
+  | { kind: 'deny'; reason: string }
+
+export function toolBudgetDecision(callNumber: number): ToolBudgetDecision {
+  if (callNumber > TOOL_BUDGET_HARD_CALL) {
+    return {
+      kind: 'deny',
+      reason: `${TOOL_BUDGET_EXHAUSTED}: maximum ${TOOL_BUDGET_HARD_CALL} real tool dispatches per agent turn reached; provide a final answer using existing results`,
+    }
+  }
+  return {
+    kind: 'allow',
+    softSignal: callNumber === TOOL_BUDGET_SOFT_CALL,
+    exhaustsBudget: callNumber === TOOL_BUDGET_HARD_CALL,
+  }
+}
+
+export function createToolBudgetState(): {
+  nextCall(): ToolBudgetDecision & { callNumber: number }
+} {
+  let calls = 0
+  return {
+    nextCall() {
+      calls += 1
+      return { ...toolBudgetDecision(calls), callNumber: calls }
+    },
+  }
+}
+
+function convergenceContext(code: 'TOOL_BUDGET_SOFT' | typeof TOOL_BUDGET_EXHAUSTED, text: string) {
+  return {
+    id: randomUUID(),
+    role: 'user' as const,
+    content: [{ type: 'text' as const, text: `${code}: ${text}` }],
+    source: { kind: 'plugin' as const, plugin: 'gotry-tool-budget' },
+  }
+}
+
+function exhaustionResult(reason: string): ToolExecutionResult {
+  return {
+    isError: true,
+    error: {
+      message: reason,
+      info: { name: 'ToolBudgetError', code: TOOL_BUDGET_EXHAUSTED },
+    },
+    content: [{ type: 'text', text: reason }],
+    additionalContexts: [convergenceContext(
+      TOOL_BUDGET_EXHAUSTED,
+      'No more tool dispatches are permitted in this turn. Produce the final answer from existing results.',
+    ) as never],
+  }
+}
+
+type RestrictableTools = {
+  schemas?: () => Array<{ name: string }>
+  restrict?: (filter: { deny: string[] }) => () => void
+}
+
+/**
+ * Install the runtime boundary, kept separate from the GoTry tool catalog so
+ * the actual Cordis waterfalls can be exercised without booting every tool.
+ */
+export function installToolBudget(ctx: Context): void {
+  // Some offline contract tests intentionally provide a registration-only
+  // Context slice. They do not drive an agent loop, so there is no budget hook
+  // to install and no reason to require an event bus.
+  if (typeof (ctx as unknown as { on?: unknown }).on !== 'function') return
+
+  const budgetByAgent = new Map<string, ReturnType<typeof createToolBudgetState>>()
+  const softExecutions = new Map<ToolExecutionToken, string>()
+  const pendingFinalOnly = new Map<string, Agent>()
+  const finalOnlyDisposers = new Map<string, () => void>()
+
+  const clearAgent = (agentId: string) => {
+    budgetByAgent.delete(agentId)
+    for (const [token, owner] of softExecutions) {
+      if (owner === agentId) softExecutions.delete(token)
+    }
+    pendingFinalOnly.delete(agentId)
+    finalOnlyDisposers.get(agentId)?.()
+    finalOnlyDisposers.delete(agentId)
+  }
+
+  const enterFinalOnly = (agent: Agent) => {
+    const agentId = String(agent.id)
+    if (finalOnlyDisposers.has(agentId)) return
+    const globalTools = ctx.tools as unknown as RestrictableTools
+    const scopedTools = agent.ctx?.tools as unknown as RestrictableTools | undefined
+    if (typeof globalTools.schemas !== 'function' || typeof scopedTools?.restrict !== 'function') return
+
+    // GoTry's model-facing tools are inherited globals. Removing their schemas
+    // makes the next native-mode request text-only; the execution wrapper below
+    // still denies any already-prepared same-step call beyond the hard limit.
+    const inheritedNames = globalTools.schemas()
+      .map(schema => schema.name)
+      .filter(name => name !== 'run_code')
+    if (inheritedNames.length === 0) return
+    finalOnlyDisposers.set(agentId, scopedTools.restrict({ deny: inheritedNames }))
+  }
+
+  ctx.on('session/event', (subject, event) => {
+    const agentId = String(subject.id)
+    if (event.type === 'turn/start' || event.type === 'turn/end') {
+      clearAgent(agentId)
+      return
+    }
+    // The live registry re-checks a tool name before starting every call in
+    // one assistant response. Restricting immediately on call 18 would turn an
+    // already-prepared call 19 into an opaque "unknown tool" before the
+    // execute waterfall can return TOOL_BUDGET_EXHAUSTED. step/end is the
+    // exact boundary after that batch settles and before the next prompt is
+    // assembled, so current-step refusals stay structured while the next
+    // native request is text-only.
+    if (event.type === 'step/end') {
+      const agent = pendingFinalOnly.get(agentId)
+      if (agent) {
+        pendingFinalOnly.delete(agentId)
+        enterFinalOnly(agent)
+      }
+    }
+  })
+  ctx.on('session/disposed', subject => clearAgent(String(subject.id)))
+
+  ctx.on('tools/execute', (exec, next) => {
+    // Programmatic/direct calls are not part of a model planner turn.
+    if (!exec.agent) return next()
+    const agentId = String(exec.agent.id)
+    const state = budgetByAgent.get(agentId) ?? createToolBudgetState()
+    budgetByAgent.set(agentId, state)
+    const decision = state.nextCall()
+    if (decision.kind === 'deny') {
+      pendingFinalOnly.set(agentId, exec.agent)
+      return Promise.resolve(exhaustionResult(decision.reason))
+    }
+    if (decision.softSignal) softExecutions.set(exec.token, agentId)
+    if (decision.exhaustsBudget) pendingFinalOnly.set(agentId, exec.agent)
+    return next()
+  })
+
+  ctx.on('tools/post-execute', (exec, _result, next) => {
+    if (!softExecutions.delete(exec.token)) return next()
+    return next().then(decision => ({
+      ...decision,
+      additionalContexts: [
+        ...(decision.additionalContexts ?? []),
+        convergenceContext(
+          'TOOL_BUDGET_SOFT',
+          'Tool call 16 reached. Converge now and produce the final answer from gathered evidence.',
+        ) as never,
+      ],
+    }))
+  })
+}