dsh-plugin-show-me-data 0.1.0

package/src/host/ai/discussion.js

@@ -0,0 +1,559 @@
+/**
+ * Discussion sessions — "talk about this indicator in a real DSH session".
+ *
+ * The panel's inline AI block answers one question from the digest and stops
+ * there: it cannot hold a conversation, change model, or be returned to later.
+ * When the deployment has an agent loop (`ctx.agents`) and a default model, this
+ * gateway opens a **real session** for the topic instead, hands it the panel's
+ * digest as context, asks the user's question, and returns the session id so the
+ * GUI can switch to it. From that point the conversation is an ordinary session:
+ * full composer, history, model picker, sidebar entry.
+ *
+ * Design notes:
+ * - every contribution is additive: the digest arrives as *context* (no wake), so
+ *   the session's first user-visible message is the user's own question;
+ * - the caller can ask for a fresh session per question or reuse a topic session;
+ * - the gateway never throws for a missing capability — it returns a structured
+ *   `unavailable` result so the panel can say what to do instead.
+ *
+ * @module host/ai/discussion
+ */
+import { fingerprint } from '../../core/insight/rank.js'
+import { buildDefaultQuestion } from '../../core/ai/prompts.js'
+
+/** How long to wait for the seeded answer before returning with `pending: true`. */
+export const REPLY_TIMEOUT_MS = 45_000
+
+/**
+ * Build one identified user-role message for the session.
+ *
+ * @param {string} text - message text.
+ * @param {{ kind: 'plugin', plugin: string }|{ kind: 'user' }} source - producer tag.
+ * @param {string} seed - identity seed.
+ * @returns {object} `UserMessage`.
+ */
+export function buildMessage(text, source, seed) {
+  return {
+    id: `smd-${fingerprint(`${seed}|${text.length}|${text.slice(0, 64)}`)}`,
+    role: 'user',
+    content: [{ type: 'text', text }],
+    source,
+  }
+}
+
+/**
+ * Compose the context block that gives a fresh session the panel's data.
+ *
+ * The session is a *real* DSH session with the plugin's own `data_*` tools, so the
+ * context has two jobs: publish the numbers behind the discussion (so nothing is
+ * quoted from memory), and say what else the panel holds — a session that believes
+ * the panel has one indicator refuses questions it could have answered.
+ *
+ * @param {object} input - context input.
+ * @param {{ zh: string, en?: string }} input.label - indicator label.
+ * @param {string} input.indicatorId - indicator id.
+ * @param {string} input.digest - the digest text (docs/06 §2.3).
+ * @param {{ from: string, to: string }} [input.range] - the panel's range.
+ * @param {string} [input.inventory] - one-line-per-indicator inventory of the rest of the panel.
+ * @returns {string} context text.
+ */
+export function buildContextText({ label, indicatorId, digest, range, inventory }) {
+  const lines = []
+  lines.push('[数据雷达] 本会话的上下文来自插件面板，不是用户输入。')
+  lines.push(`讨论主题：${label?.zh ?? indicatorId}（${indicatorId}）`)
+  if (range !== undefined) lines.push(`面板区间：${range.from} .. ${range.to}`)
+  lines.push('')
+  lines.push('只引用面板给出的数字（下面的摘要，或你用面板工具取回的数据）；不足时说明数据不足，不要凭记忆补充数值：')
+  lines.push('')
+  // An empty digest is "no data", not an empty block: the session must be told
+  // that the panel had nothing, or it will invent context.
+  const body = typeof digest === 'string' ? digest.trim() : ''
+  lines.push(body === '' ? '（无数据：面板当前没有可用的指标观测）' : body)
+  const rest = typeof inventory === 'string' ? inventory.trim() : ''
+  if (rest !== '') {
+    lines.push('')
+    lines.push(rest)
+  }
+  lines.push('')
+  lines.push('你可以直接用面板工具向数据雷达取数：data_search（搜索指标）、data_series（取某指标序列）、data_overview（面板总览）、data_digest（区间摘要）、data_health（数据源状态）。清单中的任何 id 都可以用 data_series 取完整序列。')
+  return lines.join('\n')
+}
+
+/**
+ * Read the assistant's text out of a session's event log.
+ *
+ * @param {Array<{ type?: string, data?: any }>} events - session events.
+ * @returns {{ text: string, turn: number|undefined }} the last assistant text.
+ */
+export function extractAssistantText(events) {
+  let text = ''
+  let turn
+  for (const event of events ?? []) {
+    if (event?.type !== 'assistant/message') continue
+    const blocks = event.data?.message?.content
+    if (!Array.isArray(blocks)) continue
+    const joined = blocks
+      .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+      .map((block) => block.text)
+      .join('')
+      .trim()
+    if (joined === '') continue
+    text = joined
+    turn = event.data?.turn
+  }
+  return { text, turn }
+}
+
+/**
+ * Detect a turn that *failed* rather than one that simply had nothing to say.
+ *
+ * An LLM failure (a missing credential, an upstream 5xx, a refused request)
+ * does not reject `whenIdle()`: the loop records it and goes idle. A gateway
+ * that only reads text therefore reports success with an empty reply, and the
+ * GUI shows an empty answer as if the model had answered nothing — which is
+ * exactly how "why is there no output" becomes unanswerable from the panel.
+ *
+ * @param {Array<{ type?: string, data?: any }>} events - events of the observed turn.
+ * @returns {{ message: string, code: string|undefined }|undefined} the failure.
+ */
+export function extractTurnFailure(events) {
+  let failure
+  for (const event of events ?? []) {
+    // Preferred source: the terminating chunk names provider, code and message.
+    if (event?.type === 'assistant/chunk' && event.data?.chunk?.type === 'finish') {
+      const reason = event.data.chunk.reason
+      if (reason?.kind === 'error' && typeof reason.failure?.message === 'string') {
+        failure = { message: reason.failure.message, code: reason.failure.code }
+      }
+      if (reason?.kind === 'aborted') {
+        failure = { message: '模型请求被中止（aborted）', code: reason.failure?.code }
+      }
+      continue
+    }
+    if (event?.type !== 'turn/end') continue
+    const reason = event.data?.reason
+    if (reason?.kind !== 'error' && reason?.kind !== 'aborted') continue
+    const detail = reason.error ?? reason.failure ?? {}
+    const message = typeof detail.message === 'string'
+      ? detail.message
+      : reason.kind === 'aborted' ? '模型请求被中止（aborted）' : 'turn ended with error'
+    failure = { message, code: detail.code }
+  }
+  return failure
+}
+
+/**
+ * Create the discussion gateway.
+ *
+ * @param {object} deps - dependencies.
+ * @param {object} deps.ctx - host context (for `agents`, `sessions`, `agentDefaultModel`).
+ * @param {import('../../ports/clock.js').Clock} deps.clock - clock.
+ * @param {(msg: string, meta?: object) => void} [deps.log] - logger.
+ * @param {{ timeoutMs?: number }} [deps.options] - tuning.
+ * @returns {object} gateway.
+ */
+export function createDiscussionGateway({ ctx, clock, log = () => {}, options = {} }) {
+  const timeoutMs = options.timeoutMs ?? REPLY_TIMEOUT_MS
+  const cwd = options.cwd
+  // A monotonically increasing counter keeps two discussions opened in the same
+  // millisecond from colliding on one session id (the clock alone is not unique).
+  let sequence = 0
+  /** @type {Map<string, { sessionId: string, createdAt: string, label: string, turns: number }>} */
+  const topics = new Map()
+  /** @type {Map<string, object>} */
+  const agentsByTopic = new Map()
+  /** @type {Map<string, { agent: object, askedAt: number, from: number }>} */
+  const bySession = new Map()
+  /** @type {Array<() => Promise<void>>} */
+  const live = []
+
+  /**
+   * Whether this deployment can open sessions at all.
+   *
+   * @returns {{ available: boolean, reason?: string }} capability.
+   */
+  function capability() {
+    if (ctx.get('agents') === undefined) return { available: false, reason: '本部署没有 agent 运行时（ctx.agents 不可用），无法开启独立会话。' }
+    if (ctx.get('agentDefaultModel') === undefined) return { available: false, reason: '本部署没有默认模型选择（ctx.agentDefaultModel 不可用），无法开启独立会话。' }
+    return { available: true }
+  }
+
+  /**
+   * Compose the session metadata.
+   *
+   * A discussion is a **user-visible session of its own**, not a delegated
+   * subagent: it carries the workspace and the preset but no parent lineage, so
+   * it appears in the sidebar beside other sessions and can be reopened later.
+   *
+   * @param {object} [requester] - the requesting *agent*, when the caller knows it.
+   * @param {string} [overrideCwd] - explicit workspace for the new session.
+   * @returns {object} session meta.
+   */
+  function sessionMeta(requester, overrideCwd) {
+    const requesterCwd = requester?.session?.header?.cwd
+    const sessionCwd = typeof overrideCwd === 'string' && overrideCwd !== ''
+      ? overrideCwd
+      : typeof requesterCwd === 'string' && requesterCwd !== '' ? requesterCwd : cwd
+    // Read from the requesting *agent's* scope, not from a session object: the
+    // standing mount that answers "which preset is this?" lives on the agent ctx.
+    const preset = requester?.ctx === undefined ? undefined : ctx.get('agentPresets')?.composedPreset?.(requester.ctx)
+    return {
+      ...(typeof sessionCwd === 'string' && sessionCwd !== '' ? { cwd: sessionCwd } : {}),
+      ...(typeof preset === 'string' && preset !== '' ? { agentPreset: preset } : {}),
+    }
+  }
+
+  /**
+   * Join the new agent to a composition, so it is not born into an empty world.
+   *
+   * An agent that joins no preset resolves its tools, prompt sections and skills
+   * against the empty global layer: the session sees only the tools registered on
+   * the host composition — this plugin's ten `data_*` tools — with no filesystem,
+   * no shell, no skills. An iteration session created that way told the reader it
+   * *could not edit the plugin* because it had no file tools, which is true.
+   *
+   * The requester's own composition is joined when the caller named the
+   * requesting session (the panel sends it), so the discussion runs on the same
+   * preset, tools and prompt the reader is already using. Otherwise the
+   * deployment's default preset is mounted.
+   *
+   * A failure here is logged and swallowed: composition is worth having, but it
+   * is never worth losing the session the reader asked for.
+   *
+   * @param {object} [requester] - the requesting agent, when known.
+   * @returns {((agentCtx: object) => Promise<void>)|undefined} setup hook.
+   */
+  function compositionSetup(requester) {
+    const presets = ctx.get('agentPresets')
+    if (presets === undefined) return undefined
+    if (typeof presets.composeFrom !== 'function' && typeof presets.mount !== 'function') return undefined
+    return async (agentCtx) => {
+      try {
+        if (requester?.ctx !== undefined && typeof presets.composeFrom === 'function') {
+          const joined = presets.composeFrom(agentCtx, requester.ctx)
+          if (joined !== undefined) {
+            log('discussion joined the requesting composition', { preset: joined })
+            return
+          }
+        }
+        if (typeof presets.mount === 'function') {
+          const mounted = await presets.mount(agentCtx)
+          log('discussion mounted the default composition', { preset: mounted?.id ?? presets.defaultId })
+        }
+      } catch (error) {
+        log('discussion joined no composition', { message: error?.message ?? String(error) })
+      }
+    }
+  }
+
+  /**
+   * Open a discussion about one subject: an indicator, a notable item, or a group.
+   *
+   * The subject is identified by `topicKey` ('us.cpi.yoy', 'group:US', …) which
+   * becomes the session id and the reuse key; `indicatorId` alone still works, so
+   * the single-indicator path is unchanged. Only the *context* differs between
+   * callers, and the caller builds that — this gateway never guesses what a
+   * discussion is about.
+   *
+   * @param {object} request - request.
+   * @param {string} [request.indicatorId] - indicator id (the subject, when it is one).
+   * @param {string} [request.topicKey] - subject key; defaults to `indicatorId`.
+   * @param {{ zh: string, en?: string }} [request.label] - subject label.
+   * @param {string} request.digest - digest text handed to the session as context.
+   * @param {string} [request.question] - the user's first question.
+   * @param {{ from: string, to: string }} [request.range] - panel range.
+   * @param {'new'|'topic'} [request.mode] - a fresh session each time (`new`, default) or one session per subject (`topic`).
+   * @param {string} [request.sessionId] - the requesting session, for cwd/preset/tool inheritance.
+   * @param {string} [request.cwd] - explicit working directory for the new session
+   *   (an iteration session has to start in the plugin workspace, not wherever the
+   *   requesting session happens to be).
+   * @param {boolean} [request.ask] - `false` seeds the session and asks nothing.
+   * @returns {Promise<object>} `{ ok, sessionId, reply, pending, mode, error? }`.
+   */
+  async function discuss(request = {}) {
+    const capabilityState = capability()
+    if (capabilityState.available !== true) {
+      return { ok: false, error: { kind: 'unavailable', detail: capabilityState.reason, retryable: false } }
+    }
+    const { label, digest, question, range } = request
+    const indicatorId = typeof request.topicKey === 'string' && request.topicKey !== '' ? request.topicKey : request.indicatorId
+    if (typeof indicatorId !== 'string' || indicatorId === '') {
+      return { ok: false, error: { kind: 'bad-request', detail: 'indicatorId (or topicKey) is required', retryable: false } }
+    }
+
+    const agents = ctx.get('agents')
+    const defaultModel = ctx.get('agentDefaultModel')
+    const sessions = ctx.get('sessions')
+    const selection = defaultModel.currentSelection()
+    if (selection?.provider === undefined || selection?.model === undefined) {
+      return { ok: false, error: { kind: 'unavailable', detail: '默认模型未配置（agentDefaultModel.currentSelection() 为空），无法开启独立会话。', retryable: false } }
+    }
+
+    // Which session asked. The panel sends its own id, and that one lookup buys
+    // the discussion the reader's working directory, their preset, and therefore
+    // their tools — a session created without it joins no composition at all.
+    const requester = typeof request.sessionId === 'string' && request.sessionId !== '' && typeof agents.get === 'function'
+      ? agents.get(request.sessionId)
+      : undefined
+
+    // A discussion with a context message but no question is a session where
+    // nothing happens: the context is parked in the inbox for a turn that never
+    // starts, so the GUI opens an empty session and the panel — polling for text
+    // that cannot exist — reports a model failure. The panel's buttons are
+    // labelled 「讨论」, so when the reader typed nothing we ask the subject's
+    // opening question for them and say which question that was.
+    // `ask: false` is the deliberate exception, for a caller that only wants the
+    // session seeded and will drive it itself.
+    const typed = typeof question === 'string' ? question.trim() : ''
+    const asked = typed === ''
+      ? buildDefaultQuestion({ subject: request.subject ?? 'indicator', label: label?.zh ?? indicatorId })
+      : typed
+    const seedQuestion = request.ask === false ? '' : asked
+    // "The panel asked this" is only true when it actually did.
+    const autoQuestion = seedQuestion !== '' && typed === ''
+
+    // `topic` mode continues an existing discussion; `new` (the default) opens a
+    // fresh session for every question, which is what the panel's button says.
+    const reuse = request.mode === 'topic' && agentsByTopic.has(indicatorId)
+    const topic = reuse ? topics.get(indicatorId) : undefined
+    sequence += 1
+    const sessionId = topic?.sessionId ?? `session-smd-${clock.now().getTime().toString(36)}-${sequence.toString(36)}-${fingerprint(`${indicatorId}|${clock.now().toISOString()}|${sequence}`)}`
+
+    let agent
+    if (reuse) {
+      agent = agentsByTopic.get(indicatorId)
+    } else {
+      try {
+        const setup = compositionSetup(requester)
+        const handle = await agents.create({
+          sessionId,
+          meta: sessionMeta(requester, request.cwd),
+          agentOptions: { provider: selection.provider, model: selection.model },
+          ...(setup === undefined ? {} : { setup }),
+        })
+        agent = handle.agent
+        agentsByTopic.set(indicatorId, agent)
+        live.push(async () => {
+          try {
+            await handle.dispose()
+          } catch {
+            // disposal is best-effort
+          }
+        })
+      } catch (error) {
+        log('discussion session creation failed', { indicatorId, message: error?.message ?? String(error) })
+        return {
+          ok: false,
+          error: { kind: 'session-create-failed', detail: `无法创建会话：${error?.message ?? error}`, retryable: true },
+        }
+      }
+    }
+
+    const contextText = buildContextText({ label, indicatorId, digest, range })
+    const wait = request.wait !== false
+    // The session's event log is not readable while the loop is starting a turn
+    // (observed: `session.events` is undefined between `followup()` and the turn
+    // boundary), so the cursor is taken defensively and only when it is used.
+    const eventsOf = () => (Array.isArray(agent.session?.events) ? agent.session.events : [])
+    let pending = false
+    let reply = ''
+    try {
+      // Registered before the turn so `answer()` can always find the session,
+      // including the context-only case: the panel polls as soon as it has an
+      // id, and a 404 there would leave "正在生成" on screen for good.
+      bySession.set(sessionId, { agent, askedAt: clock.now().getTime(), from: eventsOf().length, asked: seedQuestion !== '' })
+      if (seedQuestion !== '') {
+        // The context travels as a `pre-turn` message in the SAME turn as the
+        // question. A `between-turns` context message is only claimed when the
+        // session runs another turn, so a session whose first turn is this very
+        // question would otherwise see no panel data at all.
+        agent.send(
+          buildMessage(contextText, { kind: 'plugin', plugin: 'show-me-data' }, `ctx|${sessionId}`),
+          // `InboxTarget` is the string union 'next-turn' | 'next-step'.
+          'next-turn',
+          false,
+        )
+        const firstSeq = eventsOf().length
+        // The context message already counted toward the cursor; the answer is
+        // whatever the turn produces after it.
+        bySession.set(sessionId, { agent, askedAt: clock.now().getTime(), from: firstSeq, asked: true })
+        // A question the panel wrote for the reader is tagged as the plugin's, not
+        // as the reader's: the transcript must not claim the user typed it.
+        agent.followup(buildMessage(seedQuestion, autoQuestion ? { kind: 'plugin', plugin: 'show-me-data' } : { kind: 'user' }, `q|${sessionId}`))
+        if (wait) {
+          const settled = await withTimeout(agent.whenIdle(), timeoutMs)
+          // A timeout is not a failure: the turn is still running in a real
+          // session the caller can open, so answer 200 and say it is pending
+          // rather than turning a slow model into an error.
+          pending = settled === 'timeout'
+          const observed = eventsOf().slice(firstSeq)
+          const failure = settled === 'timeout' ? undefined : extractTurnFailure(observed)
+          if (failure !== undefined) {
+            // The session exists and is worth keeping: hand its id back so the
+            // GUI can still switch there, but never pretend the turn succeeded.
+            log('discussion turn failed', { indicatorId, sessionId, code: failure.code, message: failure.message })
+            return {
+              ok: false,
+              sessionId,
+              question: asked,
+              autoQuestion,
+              error: {
+                kind: 'session-turn-failed',
+                detail: `会话已创建，但模型请求失败：${failure.message}`,
+                retryable: true,
+              },
+            }
+          }
+          const { text } = extractAssistantText(observed)
+          reply = text
+        } else {
+          // The caller asked not to wait: the turn runs in this session, and the
+          // GUI it opens will show the answer as it streams.
+          pending = true
+        }
+      } else {
+        // `ask: false`: keep the panel data ready for whatever the reader asks
+        // first, so opening a seeded session and typing there has the context.
+        // Nothing runs, so the answer state is `idle`, never "done and empty".
+        agent.send(
+          buildMessage(contextText, { kind: 'plugin', plugin: 'show-me-data' }, `ctx|${sessionId}`),
+          'next-turn',
+          false,
+        )
+      }
+    } catch (error) {
+      // The session exists but driving its first turn failed: say so with the
+      // cause instead of letting it surface as a bare 500.
+      log('discussion turn failed', { indicatorId, sessionId, message: error?.message ?? String(error) })
+      return {
+        ok: false,
+        sessionId,
+        question: asked,
+        autoQuestion,
+        error: {
+          kind: 'session-turn-failed',
+          detail: `会话已创建，但首轮提问失败：${error?.message ?? error}`,
+          retryable: true,
+        },
+      }
+    }
+
+    topics.set(indicatorId, {
+      sessionId,
+      createdAt: clock.now().toISOString(),
+      label: label?.zh ?? indicatorId,
+      turns: (topic?.turns ?? 0) + (seedQuestion === '' ? 0 : 1),
+    })
+    // Persist the discussion so it survives a restart and shows up in the
+    // session list. The loop's checkpoint policy may still be settling when
+    // `whenIdle()` resolves, so the flush is retried briefly: a session that
+    // exists but was never written is worse than one extra read.
+    if (sessions !== undefined && sessions.flush !== undefined) {
+      for (let attempt = 1; attempt <= 3; attempt += 1) {
+        try {
+          const flushed = await sessions.flush(agent.session)
+          if (flushed !== false) break
+        } catch (error) {
+          log('discussion flush failed', { attempt, message: error?.message ?? String(error) })
+        }
+        await new Promise((resolve) => {
+          const timer = setTimeout(resolve, 150 * attempt)
+          if (typeof timer.unref === 'function') timer.unref()
+        })
+      }
+    }
+
+    log('discussion opened', { indicatorId, sessionId, mode: reuse ? 'topic' : 'new', replyChars: reply.length, pending })
+    return {
+      ok: true,
+      sessionId,
+      mode: reuse ? 'topic' : 'new',
+      reply,
+      pending,
+      question: asked,
+      autoQuestion,
+      provider: selection.provider,
+      model: selection.model,
+      topic: { turns: topics.get(indicatorId).turns },
+    }
+  }
+
+  /**
+   * Collect the answer to a discussion that was opened with `wait: false`.
+   *
+   * The panel opens the session and switches to it immediately, so its own
+   * request cannot also wait for the turn. This is how the panel comes back for
+   * the answer a few seconds later instead of leaving the block empty until the
+   * reader notices the new session.
+   *
+   * @param {string} sessionId - session id returned by `discuss()`.
+   * @returns {{ status: 'unknown'|'idle'|'pending'|'done'|'failed', reply?: string, error?: { kind: string, detail: string }, eventCount?: number }} state.
+   */
+  function answer(sessionId) {
+    const entry = bySession.get(sessionId)
+    if (entry === undefined) return { status: 'unknown' }
+    const events = Array.isArray(entry.agent.session?.events) ? entry.agent.session.events : []
+    const observed = events.slice(entry.from)
+    const { text } = extractAssistantText(observed)
+    const failure = extractTurnFailure(observed)
+    if (failure !== undefined) {
+      return { status: 'failed', error: { kind: 'session-turn-failed', detail: failure.message }, eventCount: events.length }
+    }
+    // A seeded session nobody asked anything in has no answer to wait for. It is
+    // 'idle', not 'done with empty text': reporting the latter made the panel
+    // diagnose a model failure for a session that was simply never asked.
+    if (entry.asked !== true) return { status: 'idle', reply: text, eventCount: events.length }
+    const active = entry.agent.status === 'running' || entry.agent.status?.kind === 'running'
+    // While the turn is still running, text may only be the model narrating a tool
+    // call ("let me inspect the workspace source of truth") — reporting that as
+    // the answer left the panel showing a half-sentence instead of the conclusion.
+    // The final text is read once the agent is idle again.
+    if (active) return { status: 'pending', eventCount: events.length }
+    return { status: 'done', reply: text, eventCount: events.length }
+  }
+
+  /**
+   * The sessions this plugin opened in this process.
+   *
+   * @returns {Array<{ indicatorId: string, sessionId: string, createdAt: string, turns: number }>} topics.
+   */
+  function list() {
+    return [...topics.entries()].map(([indicatorId, entry]) => ({ indicatorId, ...entry }))
+  }
+
+  /**
+   * Dispose every session this plugin opened.
+   *
+   * @returns {Promise<void>} completion.
+   */
+  async function dispose() {
+    const pendingDisposals = live.splice(0, live.length)
+    await Promise.allSettled(pendingDisposals.map((disposeOne) => disposeOne()))
+    topics.clear()
+    agentsByTopic.clear()
+    bySession.clear()
+  }
+
+  return { discuss, answer, list, dispose, capability }
+}
+
+/**
+ * Await a promise with a budget.
+ *
+ * @param {Promise<any>} promise - promise to await.
+ * @param {number} ms - budget.
+ * @returns {Promise<'settled'|'timeout'>} outcome.
+ */
+async function withTimeout(promise, ms) {
+  let timer
+  try {
+    return await Promise.race([
+      promise.then(() => 'settled'),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), ms)
+      }),
+    ])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}