@chentyit/dsh-chatbot-panel 0.0.0-stage → 0.1.0

package/icon.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="ChatBot capability panel">
+  <defs>
+    <linearGradient id="cbp-bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#101319"/>
+      <stop offset="1" stop-color="#2a3342"/>
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="60" height="60" rx="16" fill="url(#cbp-bg)"/>
+  <path d="M14 22.5c0-3 2.4-5.5 5.4-5.5h25.2c3 0 5.4 2.5 5.4 5.5v14c0 3-2.4 5.5-5.4 5.5H29.6l-8.4 7.2c-.8.7-2 .1-2-1V42h-.8c-2.4 0-4.4-2-4.4-4.5z" fill="#f7f8fb"/>
+  <circle cx="24" cy="29.5" r="2.6" fill="#101319"/>
+  <circle cx="32" cy="29.5" r="2.6" fill="#101319"/>
+  <circle cx="40" cy="29.5" r="2.6" fill="#101319"/>
+  <circle cx="47" cy="47" r="9" fill="#4b8bf5"/>
+  <path d="M43 47h8M47 43v8" stroke="#fff" stroke-width="2.2" stroke-linecap="round"/>
+</svg>

package/index.js

@@ -0,0 +1,651 @@
+/**
+ * Host half of the ChatBot capability panel bundle.
+ *
+ * Owns three things:
+ *  1. Per-session capability state (`chatbotCapabilities` projection), derived
+ *     from the `/chatbot` command lifecycle events that the Session log already
+ *     records — no new Session event type is introduced.
+ *  2. Tool gating: while web capability is off, the built-in `web_search` /
+ *     `web_fetch` tools are restricted away from that agent, so they disappear
+ *     from the model's tool catalog; the optional deep-thinking search tool is
+ *     declared only while both capabilities are on.
+ *  3. Usage and cost accounting (`chatbotUsage` projection), folded from the
+ *     `tool/call` + `tool/result` events: successful REST searches are billed
+ *     per query (one request per query), fetches only when the DeepSeek Fetch
+ *     provider serves them, and deep searches report their own billed tool
+ *     counts and auxiliary model tokens.
+ *
+ * The browser half renders the capsule and the upward panel; it reads both
+ * projections through `useProjection` and writes through `/chatbot ...`.
+ */
+
+/** Capability projection key. */
+const CAP_KEY = 'chatbotCapabilities'
+/** Usage projection key. */
+const USAGE_KEY = 'chatbotUsage'
+/** Built-in tools the panel hides while the web capability is off. */
+const BUILTIN_WEB_TOOLS = ['web_search', 'web_fetch']
+/** Built-in search tool name. */
+const SEARCH_TOOL = 'web_search'
+/** Built-in fetch tool name. */
+const FETCH_TOOL = 'web_fetch'
+/** Panel-owned deep-thinking search tool name. */
+const DEEP_TOOL = 'chatbot_deep_search'
+/** Fallback platform usage page. */
+const USAGE_URL = 'https://platform.deepseek.com/usage'
+/** Anthropic-compatible API version header. */
+const ANTHROPIC_VERSION = '2023-06-01'
+/** Upper bound on remembered open tool calls inside the usage projection. */
+const MAX_OPEN_CALLS = 64
+/** Duck-typed schema: the projection registry only calls `parse`. */
+const passthroughSchema = { parse: value => value }
+
+/** Resolve the deployment config from the raw Loader row value. */
+function resolveConfig(raw) {
+  const source = raw !== null && typeof raw === 'object' ? raw : {}
+  const deepSource = source.deepSearch !== null && typeof source.deepSearch === 'object' ? source.deepSearch : {}
+  const tokenSource = source.tokenPrice !== null && typeof source.tokenPrice === 'object' ? source.tokenPrice : {}
+  const positive = (value, fallback) => (typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback)
+  const nonNegative = (value, fallback) => (typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback)
+  const text = (value, fallback) => (typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallback)
+  return {
+    manageBuiltinWebTools: source.manageBuiltinWebTools !== false,
+    pricePerThousand: nonNegative(source.pricePerThousand, 5),
+    countFetchCost: source.countFetchCost === true,
+    deepSearch: {
+      baseURL: text(deepSource.baseURL, 'https://api.deepseek.com/anthropic/v1').replace(/\/+$/u, ''),
+      apiKeyEnv: text(deepSource.apiKeyEnv, 'DEEPSEEK_API_KEY'),
+      model: text(deepSource.model, 'deepseek-flash'),
+      maxTokens: positive(deepSource.maxTokens, 4096),
+      timeoutMs: positive(deepSource.timeoutMs, 180000),
+    },
+    tokenPrice: {
+      inputPerMillion: nonNegative(tokenSource.inputPerMillion, 1),
+      outputPerMillion: nonNegative(tokenSource.outputPerMillion, 4),
+    },
+  }
+}
+
+/** Empty capability state, also the per-Session replay default. */
+function emptyCapabilities() {
+  return { web: false, deep: false, pending: null }
+}
+
+/** Empty usage state. Every field is additive and JSON-serializable. */
+function emptyUsage() {
+  return {
+    search: { calls: 0, queries: 0, sources: 0, failed: 0, failedQueries: 0 },
+    fetch: { calls: 0, failed: 0 },
+    deep: {
+      calls: 0, failed: 0, toolSearch: 0, toolFetch: 0, imageSearch: 0,
+      inputTokens: 0, outputTokens: 0, sources: 0,
+    },
+    open: {},
+  }
+}
+
+/** Parse one `/chatbot` argument string into a state patch. */
+function parseCapabilityInput(rawInput) {
+  const text = typeof rawInput === 'string' ? rawInput.trim().toLowerCase() : ''
+  if (text.length === 0 || text === 'status' || text === 'show') return { kind: 'status' }
+  if (text === 'reset') return { kind: 'patch', patch: { web: false, deep: false } }
+  const parts = text.split(/\s+/u)
+  if (parts.length !== 2) return undefined
+  const [rawKey, rawValue] = parts
+  const key = rawKey === 'deepsearch' || rawKey === 'deep-search' ? 'deep' : rawKey
+  if (key !== 'web' && key !== 'deep') return undefined
+  if (rawValue !== 'on' && rawValue !== 'off') return undefined
+  const enabled = rawValue === 'on'
+  if (key === 'web') {
+    // Turning search off also turns deep search off; deep search needs search.
+    return { kind: 'patch', patch: enabled ? { web: true } : { web: false, deep: false } }
+  }
+  // Deep search implies plain search.
+  return { kind: 'patch', patch: enabled ? { web: true, deep: true } : { deep: false } }
+}
+
+/** Apply one parsed patch to a capability state (never mutates). */
+function applyCapabilityPatch(state, patch) {
+  return {
+    web: typeof patch.web === 'boolean' ? patch.web : state.web,
+    deep: typeof patch.deep === 'boolean' ? patch.deep : state.deep,
+    pending: null,
+  }
+}
+
+/** Count the queries a `web_search` call will fan out into. */
+function queryCount(argumentsJson) {
+  try {
+    const parsed = typeof argumentsJson === 'string' ? JSON.parse(argumentsJson) : argumentsJson
+    if (parsed === null || typeof parsed !== 'object') return 0
+    const queries = parsed.queries
+    return Array.isArray(queries) ? queries.filter(item => typeof item === 'string' && item.length > 0).length : 0
+  } catch (_malformedArguments) {
+    return 0
+  }
+}
+
+/** Keep the open-call map bounded; object insertion order gives age order. */
+function trimOpenCalls(open) {
+  const keys = Object.keys(open)
+  if (keys.length <= MAX_OPEN_CALLS) return open
+  const next = { ...open }
+  for (const key of keys.slice(0, keys.length - MAX_OPEN_CALLS)) delete next[key]
+  return next
+}
+
+/** Read a finite non-negative number from a provider usage field. */
+function countOf(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0
+}
+
+/** Read an optional string field. */
+function stringOf(value) {
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+/** Build the auxiliary deep-search instruction for one batch of queries. */
+function deepInstruction(queries) {
+  if (queries.length === 1) return `Perform a deep web search for: ${queries[0]}`
+  const list = queries.map((query, index) => `${index + 1}. ${query}`).join('\n')
+  return `Perform a deep web search for these queries, reading the most relevant pages:\n${list}`
+}
+
+/** Render the deep-search tool result for the model. */
+function renderDeepResult(value) {
+  const lines = []
+  if (typeof value.answer === 'string' && value.answer.length > 0) lines.push(value.answer)
+  if (Array.isArray(value.sources) && value.sources.length > 0) {
+    lines.push('Sources:')
+    for (const source of value.sources.slice(0, 20)) {
+      lines.push(`- ${source.title === undefined ? source.url : `${source.title} — ${source.url}`}`)
+    }
+  }
+  if (lines.length === 0) lines.push('The deep search returned no usable content.')
+  return lines.join('\n')
+}
+
+/** Map one Messages payload from the auxiliary deep-search request. */
+function mapDeepResponse(payload, queries) {
+  const content = Array.isArray(payload?.content) ? payload.content : []
+  const sources = []
+  const seen = new Set()
+  const texts = []
+  for (const block of content) {
+    if (block === null || typeof block !== 'object') continue
+    if (block.type === 'text' && typeof block.text === 'string') texts.push(block.text)
+    if (block.type === 'web_search_tool_result' && Array.isArray(block.content)) {
+      for (const item of block.content) {
+        if (item === null || typeof item !== 'object' || item.type !== 'web_search_result') continue
+        const url = stringOf(item.url)
+        if (url === undefined || seen.has(url)) continue
+        seen.add(url)
+        const source = { url }
+        const title = stringOf(item.title)
+        const snippet = stringOf(item.snippet)
+        const site = stringOf(item.site_name)
+        const publishedAt = stringOf(item.page_age)
+        if (title !== undefined) source.title = title
+        if (snippet !== undefined) source.snippet = snippet
+        if (site !== undefined) source.site = site
+        if (publishedAt !== undefined) source.publishedAt = publishedAt
+        sources.push(source)
+      }
+    }
+    if (block.type === 'web_fetch_tool_result' && block.content !== null && typeof block.content === 'object') {
+      const fetched = block.content
+      if (fetched.type === 'web_fetch_result') {
+        const url = stringOf(fetched.url)
+        if (url !== undefined && !seen.has(url)) {
+          seen.add(url)
+          const source = { url }
+          const title = stringOf(fetched.content?.title)
+          if (title !== undefined) source.title = title
+          sources.push(source)
+        }
+      }
+    }
+  }
+  const usage = payload?.usage !== null && typeof payload?.usage === 'object' ? payload.usage : {}
+  const serverTools = usage.server_tool_use !== null && typeof usage.server_tool_use === 'object'
+    ? usage.server_tool_use
+    : {}
+  return {
+    answer: texts.join('\n\n').trim(),
+    queries,
+    sources,
+    usage: {
+      toolSearch: countOf(serverTools.tool_search),
+      toolFetch: countOf(serverTools.tool_fetch),
+      imageSearch: countOf(serverTools.tool_image_search),
+      inputTokens: countOf(usage.input_tokens),
+      outputTokens: countOf(usage.output_tokens),
+    },
+  }
+}
+
+/** Resolve one auxiliary deep-search call's auth headers. */
+async function resolveDeepAuth(ctx, config, endpoint) {
+  // The account token is only meaningful for a Session running on the account
+  // route; an API-key Session keeps its own key (same rule as the built-in
+  // DeepSeek search provider). An unresolved route still prefers the signed-in
+  // account, because that is the only credential a sign-in-only profile has.
+  const agents = typeof ctx.get === 'function' ? ctx.get('agents') : undefined
+  const initiator = agents !== undefined && agents !== null && typeof agents.currentInitiator === 'function'
+    ? agents.currentInitiator()
+    : undefined
+  const route = initiator?.session?.requestContext?.()?.provider
+  const account = typeof ctx.get === 'function' ? ctx.get('deepseekAccount') : undefined
+  if ((route === undefined || route === 'deepseek-account')
+    && account !== undefined && account !== null
+    && typeof account.resolveToken === 'function') {
+    try {
+      const token = await account.resolveToken(endpoint)
+      if (typeof token === 'string' && token.length > 0) {
+        return {
+          kind: 'account',
+          headers: { 'x-dsh-auth-token': token },
+          reject: async () => {
+            if (typeof account.rejectToken === 'function') await account.rejectToken(token)
+          },
+        }
+      }
+    } catch (_accountTokenUnavailable) {
+      /* Fall through to the API key. */
+    }
+  }
+  const environment = globalThis.process !== undefined ? globalThis.process.env : undefined
+  const fromEnvironment = environment === undefined ? undefined : environment[config.deepSearch.apiKeyEnv]
+  const key = typeof fromEnvironment === 'string' && fromEnvironment.trim().length > 0
+    ? fromEnvironment.trim()
+    : undefined
+  if (key !== undefined) {
+    return { kind: 'api-key', headers: { 'x-api-key': key, authorization: `Bearer ${key}` } }
+  }
+  throw new Error(
+    `ChatBot deep search needs a credential: sign in to a DeepSeek account in DSH, `
+    + `or set ${config.deepSearch.apiKeyEnv} in $DSH_HOME/.env.`,
+  )
+}
+
+/**
+ * Host half entry point.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {unknown} rawConfig
+ */
+export const name = 'chatbot-panel'
+/** Services this plugin needs before activation. */
+export const inject = ['agents', 'sessionProjections', 'tools']
+
+export async function apply(ctx, rawConfig) {
+  const config = resolveConfig(rawConfig)
+
+  /** Live agents whose built-in web tools this plugin currently restricts. */
+  const gates = new Map()
+  /** Memoized wire views, so an unchanged state publishes no new object. */
+  let capsStateCache
+  let capsViewCache
+  let usageStateCache
+  let usageViewCache
+
+  const capabilities = {
+    key: CAP_KEY,
+    stateVersion: 1,
+    stateSchema: passthroughSchema,
+    init: () => emptyCapabilities(),
+    apply: (state, event) => {
+      if (event.type === 'command/run') {
+        if (event.data.name !== 'chatbot') return state
+        const parsed = parseCapabilityInput(event.data.args)
+        if (parsed === undefined || parsed.kind !== 'patch') return state
+        return { ...state, pending: { commandId: event.data.commandId, patch: parsed.patch } }
+      }
+      if (event.type === 'command/done' && state.pending !== null && event.data.commandId === state.pending.commandId) {
+        if (event.data.kind !== 'success') return { ...state, pending: null }
+        return applyCapabilityPatch(state, state.pending.patch)
+      }
+      return state
+    },
+    wire: {
+      viewSchema: passthroughSchema,
+      view: (state) => {
+        if (state === capsStateCache) return capsViewCache
+        capsStateCache = state
+        capsViewCache = { web: state.web === true, deep: state.deep === true, pending: state.pending !== null }
+        return capsViewCache
+      },
+    },
+  }
+
+  const usage = {
+    key: USAGE_KEY,
+    // v2: fix the tool/result call-id field (message.toolCallId), so earlier
+    // zero-count checkpoints must be discarded instead of reused.
+    stateVersion: 2,
+    stateSchema: passthroughSchema,
+    init: () => emptyUsage(),
+    apply: (state, event) => {
+      if (event.type === 'tool/call') {
+        const name = event.data.name
+        if (name !== SEARCH_TOOL && name !== FETCH_TOOL && name !== DEEP_TOOL) return state
+        const queries = name === SEARCH_TOOL ? queryCount(event.data.arguments) : 0
+        return {
+          ...state,
+          open: trimOpenCalls({ ...state.open, [event.data.callId]: { name, queries } }),
+        }
+      }
+      if (event.type === 'tool/result') {
+        // The durable tool result identifies its call through `message.toolCallId`
+        // (older/alternate envelopes may expose `callId` or `source.callId`).
+        const message = event.data.message
+        const callId = typeof message?.toolCallId === 'string'
+          ? message.toolCallId
+          : typeof message?.callId === 'string'
+            ? message.callId
+            : typeof message?.source?.callId === 'string' ? message.source.callId : undefined
+        const open = callId === undefined ? undefined : state.open[callId]
+        if (open === undefined) return state
+        const nextOpen = { ...state.open }
+        delete nextOpen[callId]
+        const failed = event.data.message?.isError === true
+        const meta = event.data.meta !== null && typeof event.data.meta === 'object' ? event.data.meta : {}
+        if (open.name === SEARCH_TOOL) {
+          const search = { ...state.search }
+          if (failed) {
+            search.failed += 1
+            search.failedQueries += open.queries
+          } else {
+            search.calls += open.queries
+            search.queries += open.queries
+            search.sources += Array.isArray(meta.sources) ? meta.sources.length : 0
+          }
+          return { ...state, search, open: nextOpen }
+        }
+        if (open.name === FETCH_TOOL) {
+          const fetch = { ...state.fetch }
+          if (failed) fetch.failed += 1
+          else fetch.calls += 1
+          return { ...state, fetch, open: nextOpen }
+        }
+        const deep = { ...state.deep }
+        if (failed) deep.failed += 1
+        else {
+          const deepUsage = meta.usage !== null && typeof meta.usage === 'object' ? meta.usage : {}
+          deep.calls += 1
+          deep.toolSearch += countOf(deepUsage.toolSearch)
+          deep.toolFetch += countOf(deepUsage.toolFetch)
+          deep.imageSearch += countOf(deepUsage.imageSearch)
+          deep.inputTokens += countOf(deepUsage.inputTokens)
+          deep.outputTokens += countOf(deepUsage.outputTokens)
+          deep.sources += Array.isArray(meta.sources) ? meta.sources.length : 0
+        }
+        return { ...state, deep, open: nextOpen }
+      }
+      return state
+    },
+    wire: {
+      viewSchema: passthroughSchema,
+      summary: false,
+      view: (state) => {
+        if (state === usageStateCache) return usageViewCache
+        const perCall = config.pricePerThousand / 1000
+        const searchFee = state.search.calls * perCall
+        const fetchFee = config.countFetchCost ? state.fetch.calls * perCall : 0
+        const deepToolCount = state.deep.toolSearch + state.deep.toolFetch + state.deep.imageSearch
+        const deepToolFee = deepToolCount * perCall
+        const deepTokenFee = (state.deep.inputTokens / 1e6) * config.tokenPrice.inputPerMillion
+          + (state.deep.outputTokens / 1e6) * config.tokenPrice.outputPerMillion
+        usageStateCache = state
+        usageViewCache = {
+          search: { ...state.search },
+          fetch: { ...state.fetch },
+          deep: { ...state.deep },
+          fees: {
+            search: searchFee,
+            fetch: fetchFee,
+            deepTools: deepToolFee,
+            deepTokens: deepTokenFee,
+            total: searchFee + fetchFee + deepToolFee + deepTokenFee,
+          },
+          countFetchCost: config.countFetchCost,
+          pricePerThousand: config.pricePerThousand,
+          usageUrl: USAGE_URL,
+        }
+        return usageViewCache
+      },
+    },
+  }
+
+  const capabilitiesHandle = await ctx.sessionProjections.register(capabilities)
+  await ctx.sessionProjections.register(usage)
+
+  /** Current capability state for one Session, never undefined. */
+  const capabilitiesOf = (session) => {
+    const state = capabilitiesHandle.stateOf(session)
+    return state === undefined || state === null ? emptyCapabilities() : state
+  }
+
+  /** Drop one agent's restriction, if any. */
+  const releaseGate = (agent) => {
+    const dispose = gates.get(agent)
+    if (dispose === undefined) return
+    gates.delete(agent)
+    try {
+      dispose()
+    } catch (error) {
+      ctx.logger.warn('chatbot-panel: failed to release the web-tool restriction: %o', error)
+    }
+  }
+
+  /**
+   * Make one agent's tool visibility match its capability state: while the web
+   * capability is off, built-in web tools are restricted away from this agent.
+   */
+  const syncGate = (agent, state) => {
+    if (!config.manageBuiltinWebTools) {
+      releaseGate(agent)
+      return
+    }
+    if (state.web === true) {
+      releaseGate(agent)
+      return
+    }
+    if (gates.has(agent) || agent.ctx === undefined || agent.ctx.tools === undefined) return
+    // A preset without the web tools has no restrictable name; restricting an
+    // absent name rejects, so a failure here only means nothing to hide.
+    try {
+      const dispose = agent.ctx.effect(
+        () => agent.ctx.tools.restrict({ deny: BUILTIN_WEB_TOOLS }),
+        'chatbot-panel: hide built-in web tools',
+      )
+      gates.set(agent, dispose)
+    } catch (error) {
+      ctx.logger.debug('chatbot-panel: no restrictable built-in web tools for this agent: %o', error)
+    }
+  }
+
+  // The deep-thinking search tool exists only while both capabilities are on.
+  const deepTool = {
+    name: DEEP_TOOL,
+    description:
+      'Deep thinking web search. A search model plans several queries, searches, opens and reads the '
+      + 'most relevant pages over multiple steps, then answers with sources. Slower, token-costlier and '
+      + 'billed per search/fetch than web_search; use it for questions that need several sources. '
+      + 'The user enables it in the ChatBot panel.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['queries'],
+      properties: {
+        queries: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 3,
+          items: { type: 'string' },
+          description: '1–3 focused search queries.',
+        },
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['answer', 'sources', 'queries', 'usage'],
+        properties: {
+          answer: { type: 'string' },
+          queries: { type: 'array', items: { type: 'string' } },
+          sources: {
+            type: 'array',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              required: ['url'],
+              properties: {
+                url: { type: 'string' },
+                title: { type: 'string' },
+                snippet: { type: 'string' },
+                site: { type: 'string' },
+                publishedAt: { type: 'string' },
+              },
+            },
+          },
+          usage: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['toolSearch', 'toolFetch', 'imageSearch', 'inputTokens', 'outputTokens'],
+            properties: {
+              toolSearch: { type: 'number' },
+              toolFetch: { type: 'number' },
+              imageSearch: { type: 'number' },
+              inputTokens: { type: 'number' },
+              outputTokens: { type: 'number' },
+            },
+          },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: renderDeepResult(value) }],
+      presentationMeta: (_args, value) => ({
+        card: 'chatbot-deep-search',
+        answer: value.answer,
+        sources: value.sources,
+        usage: value.usage,
+      }),
+    },
+    timeoutMs: config.deepSearch.timeoutMs,
+    isConcurrencySafe: () => false,
+    async execute(args, exec) {
+      const queries = Array.isArray(args?.queries)
+        ? args.queries.filter(item => typeof item === 'string' && item.trim().length > 0).map(item => item.trim())
+        : []
+      if (queries.length === 0 || queries.length > 3) {
+        throw new Error('chatbot_deep_search needs 1–3 non-empty queries')
+      }
+      const endpoint = `${config.deepSearch.baseURL}/messages`
+      const auth = await resolveDeepAuth(ctx, config, endpoint)
+      const body = {
+        model: config.deepSearch.model,
+        max_tokens: config.deepSearch.maxTokens,
+        thinking: { type: 'enabled' },
+        tools: [{ type: 'deepseek_web_search', name: 'deepseek_web_search' }],
+        messages: [{ role: 'user', content: [{ type: 'text', text: deepInstruction(queries) }] }],
+      }
+      let response
+      try {
+        response = await fetch(endpoint, {
+          method: 'POST',
+          redirect: 'error',
+          headers: {
+            ...auth.headers,
+            'anthropic-version': ANTHROPIC_VERSION,
+            'content-type': 'application/json',
+            accept: 'application/json',
+            'user-agent': 'dsh-chatbot-panel/0.1.0',
+          },
+          body: JSON.stringify(body),
+          signal: exec.signal,
+        })
+      } catch (error) {
+        if (exec.signal.aborted) throw error
+        throw new Error(`ChatBot deep search request failed at ${endpoint}: ${String(error)}`)
+      }
+      if (!response.ok) {
+        let detail = `HTTP ${response.status}`
+        try {
+          const parsed = await response.json()
+          const message = typeof parsed?.error === 'string' ? parsed.error : parsed?.error?.message ?? parsed?.message
+          if (typeof message === 'string' && message.length > 0) detail += `: ${message}`
+        } catch (_unreadableErrorBody) {
+          /* The HTTP status is the actionable part. */
+        }
+        if (response.status === 401 && auth.kind === 'account' && typeof auth.reject === 'function') {
+          try { await auth.reject() } catch (_credentialRemovalFailed) { /* report the original failure */ }
+          throw new Error(
+            `ChatBot deep search was rejected (${detail}); the DeepSeek account sign-in is no longer valid, `
+            + 'sign in again or configure an API key in $DSH_HOME/.env.',
+          )
+        }
+        throw new Error(`ChatBot deep search was rejected (${detail}) at ${endpoint}`)
+      }
+      let payload
+      try {
+        payload = await response.json()
+      } catch (error) {
+        throw new Error(`ChatBot deep search returned an unreadable response: ${String(error)}`)
+      }
+      return mapDeepResponse(payload, queries)
+    },
+  }
+
+  ctx.tools.register(deepTool, {
+    when: ({ agent }) => {
+      const state = capabilitiesOf(agent.session)
+      return state.web === true && state.deep === true
+    },
+  })
+
+  // Existing agents (this plugin may activate after sessions started).
+  for (const agent of ctx.agents.list()) syncGate(agent, capabilitiesOf(agent.session))
+  ctx.on('agent/created', ({ agent }) => { syncGate(agent, capabilitiesOf(agent.session)) })
+  ctx.on('agent/disposed', ({ agent }) => { gates.delete(agent) })
+  ctx.effect(() => () => {
+    for (const dispose of gates.values()) {
+      try {
+        dispose()
+      } catch (_disposeFailure) {
+        /* Agent disposal already owns the registration. */
+      }
+    }
+    gates.clear()
+  }, 'chatbot-panel: release web-tool restrictions')
+
+  // The command child activates only when a command registry is composed.
+  ctx.inject(['commands'], (commandCtx) => {
+    commandCtx.commands.register({
+      definitionId: 'chatbot-panel',
+      name: 'chatbot',
+      description: 'Toggle the ChatBot capabilities of this session: /chatbot web on|off, deep on|off, reset',
+      input: { hint: 'web on|off · deep on|off · reset' },
+      handler: ({ agent, rawInput }) => {
+        const parsed = parseCapabilityInput(rawInput)
+        if (parsed === undefined) {
+          return {
+            kind: 'error',
+            text: 'Usage: /chatbot web on|off · /chatbot deep on|off · /chatbot reset',
+          }
+        }
+        const current = capabilitiesOf(agent.session)
+        if (parsed.kind === 'status') {
+          return {
+            kind: 'success',
+            text: `ChatBot capabilities: web ${current.web ? 'on' : 'off'}, deep ${current.deep ? 'on' : 'off'}`,
+          }
+        }
+        const next = applyCapabilityPatch(current, parsed.patch)
+        // Apply the gating now: the projection picks the same value up from the
+        // command events this invocation records.
+        syncGate(agent, next)
+        return { kind: 'success' }
+      },
+    })
+  })
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "ChatBot capability panel",
+    "description": "Adds a ChatBot chip right of the composer's permission chip (Workspace Write). Clicking it opens a capability panel; enabling Web search or Deep thinking search starts that capability for the current session, and while a capability is off the matching tools leave the model's tool catalog entirely. The panel footer records search, fetch and deep-search counts plus an estimated cost at the official price (CNY 5 per 1,000 successful web-tool requests), with a link to the platform usage page. Capabilities default to off and the choice is stored per session, surviving reloads and resume."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "ChatBot 能力面板",
+    "description": "在输入框「工作区内修改」权限按钮右侧加一个 ChatBot 按钮：点击展开能力面板，勾选「联网搜索」或「深度思考搜索」即在本会话启用对应能力；未启用时相应工具会从模型的工具目录中彻底移除。面板底部按官方计费口径记录搜索、抓取、深搜的次数与估算费用（搜索/抓取 ¥5/千次成功请求），并提供开放平台用量页入口。能力默认关闭，开关按会话保存，刷新页面、恢复会话后仍然有效。"
+  }
+}