refactor(gui): rework ui-question to the terminal slot standard

Contract face moves to contract/slots.ts (PropsRuntime composition off the
conversation SlotMap entry, flat answer/cancel injected share); apply takes
the ui-sidebar terminal form (strict need() service reads, ctx.effect-wrapped
single register, framework-resolved sessionId); tests upgrade to the terminal
style (props-direct component specs with standard-kit stubs, real-registry
apply spec with children-declared slot, fiber-teardown case).

packages/client/ui-question/src/client/QuestionComposer.tsx

@@ -1,16 +1,12 @@
 import { useState, type KeyboardEvent } from 'react'
 import clsx from 'clsx'
-import type { QuestionResponsePayload } from '@deepseek-ai/dsh-client-connection/client'
 import {
   Button, IconCheckOutline16, IconChevronLeftOutline14, IconChevronRightOutline14,
   IconCloseOutline16, IconEditOutline16,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { QuestionComposerOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { QuestionAnswer, QuestionComposerProps } from './contract/slots.ts'
 import css from './QuestionComposer.module.css'
 
-type QuestionInteraction = QuestionComposerOwnerProps['interaction']
-type Answer = QuestionResponsePayload['answer']
-
 interface DraftAnswer {
   selected: string[]
   custom: string
@@ -18,19 +14,6 @@ interface DraftAnswer {
   skipped: boolean
 }
 
-/** Actions assembled from the session object layer. */
-export interface QuestionComposerInjected {
-  actions: {
-    answer(interaction: QuestionInteraction, answer: Answer): Promise<void>
-    cancel(interaction: QuestionInteraction): Promise<void>
-  }
-}
-
-/** Consumed question-composer props: the slot's owner share & the injected
- *  share. A strict subset of the composed props the register site proves
- *  (the framework session/global standard kit goes unconsumed here). */
-export type QuestionComposerProps = QuestionComposerOwnerProps & QuestionComposerInjected
-
 /**
  * Split the conventional recommendation suffix without changing the answer value.
  * @param label - Original option label returned if selected.
@@ -66,7 +49,7 @@ export function QuestionComposer(props: QuestionComposerProps) {
   return <QuestionFlow key={props.interaction.rpcId} {...props} />
 }
 
-function QuestionFlow({ interaction, actions }: QuestionComposerProps) {
+function QuestionFlow({ interaction, answer: submitAnswer, cancel }: QuestionComposerProps) {
   const questions = interaction.questions
   const [index, setIndex] = useState(0)
   const [drafts, setDrafts] = useState<DraftAnswer[]>(() => questions.map(question => ({
@@ -81,7 +64,7 @@ function QuestionFlow({ interaction, actions }: QuestionComposerProps) {
   const cancelFlow = (): void => {
     setBusy('cancel')
     setError(null)
-    void actions.cancel(interaction).catch((cause: unknown) => {
+    void cancel(interaction).catch((cause: unknown) => {
       setBusy(null)
       setError(cause instanceof Error ? cause.message : String(cause))
     })
@@ -122,7 +105,7 @@ function QuestionFlow({ interaction, actions }: QuestionComposerProps) {
       setError('请先完成这道问题。')
       return
     }
-    const answer: Answer = {
+    const answer: QuestionAnswer = {
       answers: questions.map((item, itemIndex) => {
         const value = values[itemIndex] as DraftAnswer
         if (value.skipped) return { id: item.id, selected: [] }
@@ -136,7 +119,7 @@ function QuestionFlow({ interaction, actions }: QuestionComposerProps) {
     }
     setBusy('answer')
     setError(null)
-    void actions.answer(interaction, answer).catch((cause: unknown) => {
+    void submitAnswer(interaction, answer).catch((cause: unknown) => {
       setBusy(null)
       setError(cause instanceof Error ? cause.message : String(cause))
     })

packages/client/ui-question/src/client/contract/slots.ts

@@ -0,0 +1,42 @@
+/**
+ * Question-composer slot contract: the registrant-side props composition for
+ * the conversation-owned `conversation.composer` keyed slot. The own injected
+ * share is declared here (a share's type lives with whoever wires it); the
+ * runtime share — the owner-dispatched `interaction` plus the framework
+ * session/global standard kit — is PropsRuntime<'conversation.composer'>,
+ * resolved off ui-conversation's SlotMap declaration and never re-stated.
+ * Single domain — this is the package's whole contract surface.
+ */
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+// Also pulls ui-conversation's SlotMap merge (the 'conversation.composer'
+// entry) into every program that sees this contract, so PropsRuntime resolves.
+import type { QuestionComposerOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { QuestionResponsePayload } from '@deepseek-ai/dsh-client-connection/client'
+
+/** The pending question interaction the owner dispatches into the keyed slot. */
+export type QuestionInteraction = QuestionComposerOwnerProps['interaction']
+
+/** One structured answer batch covering every question of the request. */
+export type QuestionAnswer = QuestionResponsePayload['answer']
+
+/**
+ * Registrant-private injected share (arrives via the register inject
+ * factory): plain session-scoped callbacks only — the question data rides the
+ * owner share and drafts are component-local. A type alias, not an interface:
+ * the alias carries an implicit index signature, so the factory's return
+ * crosses the registry's `Record<string, unknown>` boundary uncast.
+ */
+export type QuestionComposerInjected = {
+  /** Deliver the whole answer batch; a rejected receipt surfaces as a thrown error. */
+  answer: (interaction: QuestionInteraction, answer: QuestionAnswer) => Promise<void>
+  /** Reject the whole wait (the host resolves the tool call as cancelled). */
+  cancel: (interaction: QuestionInteraction) => Promise<void>
+}
+
+/**
+ * Full component props: the framework runtime share (owner `interaction` +
+ * session/global standard kit) plus the own injected share. No children are
+ * declared and no store is registered, so no PropsRenderSlots/PropsStore
+ * term appears.
+ */
+export type QuestionComposerProps = PropsRuntime<'conversation.composer'> & QuestionComposerInjected

packages/client/ui-question/src/client/index.ts

@@ -1,50 +1,66 @@
 /**
- * Web question plugin, browser half: registers a composer replacement for
- * pending ask_user_question requests into the conversation-declared keyed
- * `conversation.composer` slot (single register API — the slot exists because
- * the conversation entry's children declaration created it).
+ * Web question plugin, browser half: QuestionComposer registered as the
+ * `question` entry of the conversation-declared keyed `conversation.composer`
+ * slot. Pure consumer — the pending interaction arrives through the owner
+ * share at the dispatch site, drafts are component-local, and the inject
+ * surface is plain session-scoped callbacks closed over the plugin's own ctx
+ * (slot design sections 5 and 6); props composition in contract/slots.ts.
+ * Export discipline: packages/client/AGENTS.md.
  */
-import type { Context } from 'cordis'
-import type { SessionId, SessionsService, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
-import { QuestionComposer, type QuestionComposerInjected } from './QuestionComposer.tsx'
+import type { ClientContext, SessionId, SessionsService, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { QuestionComposerInjected } from './contract/slots.ts'
+import { QuestionComposer } from './QuestionComposer.tsx'
 
-export { QuestionComposer, parseRecommendedLabel } from './QuestionComposer.tsx'
-export type { QuestionComposerInjected, QuestionComposerProps } from './QuestionComposer.tsx'
+export type {
+  QuestionAnswer, QuestionComposerInjected, QuestionComposerProps, QuestionInteraction,
+} from './contract/slots.ts'
 
-/** Required browser services. */
+/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
 export const inject = ['slots', 'sessions']
 
-/**
- * Register the question composer into the conversation-owned keyed slot.
- * @param ctx - Browser plugin context carrying slots and sessions.
- */
-export function apply(ctx: Context): void {
-  const slots = ctx.get('slots') as SlotsService | undefined
-  const sessions = ctx.get('sessions') as SessionsService | undefined
-  if (slots === undefined || sessions === undefined) {
-    throw new Error('ui-question: slots and sessions services are required')
-  }
-  slots.register({
-    name: 'conversation.composer',
-    key: 'question',
-    inject: (sessionId: SessionId): QuestionComposerInjected => {
-      const session = sessions.manager.get(sessionId)
-      return {
-        actions: {
-          async answer(interaction, answer) {
-            const receipt = await session.answerQuestion(interaction.rpcId, answer)
-            if (!receipt.accepted) {
-              throw new Error(`question response rejected: ${receipt.reason}`)
-            }
-          },
-          async cancel(interaction) {
-            const receipt = await session.cancelQuestion(interaction.rpcId)
-            if (!receipt.accepted) {
-              throw new Error(`question cancellation rejected: ${receipt.reason}`)
-            }
-          },
-        },
-      }
-    },
-  }, QuestionComposer)
+/** Resolve a service via ctx.get, failing loud. This package's program holds
+ *  the node half's host-side Context merges too (tool-ask-user), so property
+ *  access would resolve the colliding host `sessions` seat — same budgeted
+ *  cast as ui-conversation's need(). */
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- caller-named cast target
+function need<T>(ctx: ClientContext, name: string): T {
+  const value = ctx.get(name) as T | undefined
+  if (value === undefined) throw new Error(`ui-question: ${name} service unavailable`)
+  return value
+}
+
+/**
+ * Client plugin body: register the question composer into the keyed composer
+ * slot. The inject factory returns receipt-checked answer/cancel callbacks
+ * only (no hooks, no store lines) — the framework resolves the sessionId, and
+ * the question payload rides the owner share.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  const slots = need<SlotsService>(ctx, 'slots')
+  const sessions = need<SessionsService>(ctx, 'sessions')
+  const injectProps = (sessionId: SessionId): QuestionComposerInjected => {
+    const session = sessions.manager.get(sessionId)
+    return {
+      answer: async (interaction, answer) => {
+        const receipt = await session.answerQuestion(interaction.rpcId, answer)
+        if (!receipt.accepted) {
+          throw new Error(`question response rejected: ${receipt.reason}`)
+        }
+      },
+      cancel: async (interaction) => {
+        const receipt = await session.cancelQuestion(interaction.rpcId)
+        if (!receipt.accepted) {
+          throw new Error(`question cancellation rejected: ${receipt.reason}`)
+        }
+      },
+    }
+  }
+  ctx.effect(
+    () => slots.register(
+      { name: 'conversation.composer', key: 'question', inject: injectProps },
+      QuestionComposer,
+    ),
+    'ui-question: composer slot registration',
+  )
 }

packages/client/ui-question/tests/browser-plugin.spec.ts

@@ -1,12 +1,20 @@
+/**
+ * apply wiring on a real cordis Context + SlotsService (terminal register
+ * form): QuestionComposer registered as the `question` entry of the
+ * conversation-declared keyed composer slot, the thin inject surface (two
+ * receipt-checked session callbacks closed over the plugin ctx — no hooks, no
+ * store lines), load-order fail-loud, and fiber-teardown unregistration.
+ * Component behavior is covered props-direct in question-composer.spec.tsx;
+ * no renderer machinery here.
+ */
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
-import type { PendingInteraction, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { QuestionComposerInjected, QuestionInteraction } from '../src/client/contract/slots.ts'
 import { apply, inject } from '../src/client/index.ts'
 
-type QuestionInteraction = Extract<PendingInteraction, { kind: 'question' }>
-
 function interaction(): QuestionInteraction {
   return {
     kind: 'question', rpcId: RpcId('question-1'),
@@ -14,56 +22,88 @@ function interaction(): QuestionInteraction {
   }
 }
 
-/** Declare the conversation-owned composer slot the way production does: a
- *  parent entry's children table (register is the single declaration API). */
-function declareComposerSlot(slots: SlotsService): void {
-  slots.register({
-    name: 'root',
-    children: { 'conversation.composer': { kind: 'keyed', scope: 'session' } },
-  } as never, (() => null) as never)
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  const answerQuestion = vi.fn()
+    .mockResolvedValueOnce({ accepted: true })
+    .mockResolvedValueOnce({ accepted: false, reason: 'not-pending' })
+  const cancelQuestion = vi.fn()
+    .mockResolvedValueOnce({ accepted: true })
+    .mockResolvedValueOnce({ accepted: false, reason: 'bad-response' })
+  const get = vi.fn(() => ({ answerQuestion, cancelQuestion }))
+  ctx.provide('sessions', { manager: { get } })
+  const slots = ctx.get('slots') as SlotsService
+  // Stand-in for ui-conversation's conversation entry: the composer slot only
+  // exists while a live entry declares it in children (declaration account:
+  // design §2.2).
+  slots.register(
+    { name: 'root', children: { 'conversation.composer': { kind: 'keyed', scope: 'session' } } } as never,
+    () => null,
+  )
+  return { ctx, slots, get, answerQuestion, cancelQuestion }
 }
 
-describe('ui-question browser plugin', () => {
-  it('declares its services and fails loud without them', () => {
+/** The question entry's injected share, resolved for one session id. */
+function injectedOf(slots: SlotsService, sessionId: SessionId): QuestionComposerInjected {
+  const entries = slots.entries('conversation.composer')
+  expect(entries).toHaveLength(1)
+  // The typed StoredEntry.inject is declaration-derived ((...args: never[])
+  // shape); the question factory takes the framework-resolved sessionId.
+  const inject = entries[0]!.inject as ((id: SessionId) => QuestionComposerInjected) | undefined
+  return inject!(sessionId)
+}
+
+describe('apply', () => {
+  it('declares the services it binds', () => {
     expect(inject).toEqual(['slots', 'sessions'])
-    expect(() => { apply(new Context()) }).toThrow(/slots and sessions services are required/)
   })
 
-  it('registers scoped answer and cancel actions, including rejected receipts', async () => {
+  it('fails loud when its services are missing', () => {
+    // apply resolves both services through the strict need() reader (the
+    // program's host-side Context merge shadows typed property access).
+    expect(() => { apply(new Context()) }).toThrow(/slots service unavailable/)
+  })
+
+  it('fails loud when no live entry has declared the composer slot', async () => {
     const ctx = new Context()
     await ctx.plugin(SlotsService).await()
-    const answerQuestion = vi.fn()
-      .mockResolvedValueOnce({ accepted: true })
-      .mockResolvedValueOnce({ accepted: false, reason: 'not-pending' })
-    const cancelQuestion = vi.fn()
-      .mockResolvedValueOnce({ accepted: true })
-      .mockResolvedValueOnce({ accepted: false, reason: 'bad-response' })
-    ctx.provide('sessions', {
-      manager: { get: vi.fn(() => ({ answerQuestion, cancelQuestion })) },
-    })
-    const slots = ctx.get('slots') as SlotsService
-    declareComposerSlot(slots)
+    ctx.provide('sessions', {})
+    await expect(ctx.plugin({ inject: [...inject], apply }))
+      .rejects.toThrow(/slot "conversation.composer" is not declared/)
+  })
+
+  it('registers the question entry with the thin two-callback inject surface', async () => {
+    const { ctx, slots, get } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    expect(slots.entries('conversation.composer')[0]!.options.key).toBe('question')
+    const injected = injectedOf(slots, 'session-1' as SessionId)
+    // The whole business face: two plain callbacks, no hooks, no store lines.
+    expect(Object.keys(injected).sort()).toEqual(['answer', 'cancel'])
+    expect(get).toHaveBeenCalledWith('session-1')
+  })
+
+  it('routes answer/cancel through the session and surfaces rejected receipts', async () => {
+    const { ctx, slots, answerQuestion, cancelQuestion } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    const { answer, cancel } = injectedOf(slots, 'session-1' as SessionId)
+    const item = interaction()
+    const batch = { answers: [{ id: 'mode', selected: ['Fast'] }] }
+
+    await expect(answer(item, batch)).resolves.toBeUndefined()
+    await expect(answer(item, batch)).rejects.toThrow(/not-pending/)
+    await expect(cancel(item)).resolves.toBeUndefined()
+    await expect(cancel(item)).rejects.toThrow(/bad-response/)
+    expect(answerQuestion).toHaveBeenCalledWith(item.rpcId, batch)
+    expect(cancelQuestion).toHaveBeenCalledWith(item.rpcId)
+  })
+
+  it('teardown unregisters the slot entry', async () => {
+    const { ctx, slots } = await bench()
     const fiber = ctx.plugin({ inject: [...inject], apply })
     await fiber.await()
-
-    const entry = slots.entries('conversation.composer')[0] as unknown as {
-      options: { key: string }
-      inject(sessionId: SessionId): { actions: {
-        answer: (item: QuestionInteraction, answer: { answers: { id: string; selected: string[] }[] }) => Promise<void>
-        cancel: (item: QuestionInteraction) => Promise<void>
-      } }
-    }
-    expect(entry.options.key).toBe('question')
-    const actions = entry.inject('session-1' as SessionId).actions
-    const item = interaction()
-    const answer = { answers: [{ id: 'mode', selected: ['Fast'] }] }
-
-    await expect(actions.answer(item, answer)).resolves.toBeUndefined()
-    await expect(actions.answer(item, answer)).rejects.toThrow(/not-pending/)
-    await expect(actions.cancel(item)).resolves.toBeUndefined()
-    await expect(actions.cancel(item)).rejects.toThrow(/bad-response/)
-    expect(answerQuestion).toHaveBeenCalledWith(item.rpcId, answer)
-    expect(cancelQuestion).toHaveBeenCalledWith(item.rpcId)
-    await ctx.fiber.dispose()
+    expect(slots.entries('conversation.composer')).toHaveLength(1)
+    await fiber.dispose()
+    expect(slots.entries('conversation.composer')).toHaveLength(0)
   })
 })

packages/client/ui-question/tests/question-composer.spec.tsx

@@ -1,8 +1,9 @@
 // @vitest-environment jsdom
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
-import type { PendingInteraction } from '@deepseek-ai/dsh-client-runtime/client'
+import type { PendingInteraction, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
+import type { QuestionComposerProps } from '../src/client/contract/slots.ts'
 import {
   QuestionComposer, parseQuestionTitle, parseRecommendedLabel,
 } from '../src/client/QuestionComposer.tsx'
@@ -11,6 +12,15 @@ afterEach(cleanup)
 
 type Interaction = Extract<PendingInteraction, { kind: 'question' }>
 
+/** Framework standard-kit stubs: the composer consumes none of them, the
+ *  composed props type mandates their delivery (framework hooks are plain
+ *  stubs per the client testing discipline). */
+const kit: Pick<QuestionComposerProps, 'sessionId' | 'useSession' | 'useSessions'> = {
+  sessionId: 's1' as SessionId,
+  useSession: (() => { throw new Error('unused') }) as unknown as QuestionComposerProps['useSession'],
+  useSessions: (() => { throw new Error('unused') }) as unknown as QuestionComposerProps['useSessions'],
+}
+
 function interaction(rpcId = 'question-1'): Interaction {
   return {
     kind: 'question',
@@ -38,7 +48,7 @@ describe('QuestionComposer', () => {
   it('collects single, custom, and multi-select answers before one batch submit', () => {
     const answer = vi.fn(() => Promise.resolve())
     const cancel = vi.fn(() => Promise.resolve())
-    render(<QuestionComposer interaction={interaction()} actions={{ answer, cancel }} />)
+    render(<QuestionComposer interaction={interaction()} answer={answer} cancel={cancel} {...kit} />)
 
     expect(screen.getByText('1 / 3')).toBeTruthy()
     expect(screen.getByText('推荐')).toBeTruthy()
@@ -76,7 +86,7 @@ describe('QuestionComposer', () => {
   it('skips individual questions without discarding earlier answers', () => {
     const answer = vi.fn(() => Promise.resolve())
     const cancel = vi.fn(() => Promise.resolve())
-    render(<QuestionComposer interaction={interaction()} actions={{ answer, cancel }} />)
+    render(<QuestionComposer interaction={interaction()} answer={answer} cancel={cancel} {...kit} />)
 
     expect((screen.getByText('下一题').closest('button') as HTMLButtonElement).disabled).toBe(true)
     fireEvent.click(screen.getByRole('radio', { name: '研究潜力型' }))
@@ -98,7 +108,7 @@ describe('QuestionComposer', () => {
   it('keeps IME Enter inside the custom input until composition finishes', () => {
     const answer = vi.fn(() => Promise.resolve())
     const cancel = vi.fn(() => Promise.resolve())
-    render(<QuestionComposer interaction={interaction()} actions={{ answer, cancel }} />)
+    render(<QuestionComposer interaction={interaction()} answer={answer} cancel={cancel} {...kit} />)
 
     fireEvent.click(screen.getByRole('radio', { name: '研究潜力型' }))
     const custom = screen.getByPlaceholderText('输入你的答案')
@@ -119,7 +129,7 @@ describe('QuestionComposer', () => {
   it('opens custom input, reports missing skipped answers, and supports header navigation', () => {
     const answer = vi.fn(() => Promise.resolve())
     const cancel = vi.fn(() => Promise.resolve())
-    render(<QuestionComposer interaction={interaction()} actions={{ answer, cancel }} />)
+    render(<QuestionComposer interaction={interaction()} answer={answer} cancel={cancel} {...kit} />)
 
     fireEvent.click(screen.getByRole('button', { name: '其他，请填写自定义答案' }))
     expect(screen.getByPlaceholderText('输入你的答案')).toBeTruthy()
@@ -143,7 +153,7 @@ describe('QuestionComposer', () => {
   it('surfaces explicit cancellation rejection', async () => {
     const answer = vi.fn(() => Promise.resolve())
     const cancel = vi.fn(() => Promise.reject('取消请求失败'))
-    render(<QuestionComposer interaction={interaction()} actions={{ answer, cancel }} />)
+    render(<QuestionComposer interaction={interaction()} answer={answer} cancel={cancel} {...kit} />)
 
     fireEvent.click(screen.getByRole('button', { name: '放弃整组问题' }))
     expect(await screen.findByText('取消请求失败')).toBeTruthy()
@@ -158,11 +168,11 @@ describe('QuestionComposer', () => {
     const answer = vi.fn(() => Promise.reject(new Error('网络中断')))
     const cancel = vi.fn(() => Promise.resolve())
     const first = interaction('first')
-    const view = render(<QuestionComposer interaction={first} actions={{ answer, cancel }} />)
+    const view = render(<QuestionComposer interaction={first} answer={answer} cancel={cancel} {...kit} />)
 
     fireEvent.click(screen.getByRole('radio', { name: /研究潜力型/ }))
     expect(screen.getByText('2 / 3')).toBeTruthy()
-    view.rerender(<QuestionComposer interaction={interaction('second')} actions={{ answer, cancel }} />)
+    view.rerender(<QuestionComposer interaction={interaction('second')} answer={answer} cancel={cancel} {...kit} />)
     expect(screen.getByRole('radio', { name: /研究潜力型/ }).getAttribute('aria-checked')).toBe('false')
 
     fireEvent.click(screen.getByRole('radio', { name: /工程落地型/ }))