Add ask_user_question interaction tool

packages/core/tool-ask-user/README.md

@@ -0,0 +1,18 @@
+# @deepseek-ai/dsh-tool-ask-user
+
+Model-facing `ask_user_question` tool over `ctx.userInteraction`. It lets the model ask the human a concise question when it needs confirmation, a choice, or missing information before continuing.
+
+## Tool
+
+`ask_user_question` accepts:
+
+- `question` — required question text.
+- `header` — optional short heading.
+- `options` — optional choices with `label`, `value`, `description`, and `recommended`.
+- `allow_custom` — whether free-form answers are allowed; defaults to the provider's normal `true` behavior.
+
+The tool calls `ctx.userInteraction.ask()` and returns the selected option value or custom answer as a text tool result.
+
+## Role
+
+This is the consumer package for the user-interaction seam. It does not render UI and does not know how input is collected; it only translates model arguments into `AskUserQuestionRequest` and returns the human answer to the agent loop.

packages/core/tool-ask-user/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@deepseek-ai/dsh-tool-ask-user",
+  "description": "Model-facing ask_user_question tool over the ctx.userInteraction seam",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/core/tool-ask-user/src/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Model-facing `ask_user_question` tool over the `ctx.userInteraction` seam.
+ * The tool pauses until a UI provider returns a human answer, then feeds that
+ * answer back into the agent loop as an ordinary tool result.
+ *
+ * @module @deepseek-ai/dsh-tool-ask-user
+ */
+
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type {} from '@deepseek-ai/dsh-user-interaction'
+
+export const name = 'tool-ask-user'
+export const inject = ['tools', 'userInteraction']
+
+const description = 'Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. '
+  + 'Use options when possible; mark the recommended option when one is safest.'
+
+export function apply(ctx: Context): void {
+  ctx.tools.register(defineTool({
+    name: 'ask_user_question',
+    description,
+    parameters: {
+      header: {
+        type: 'string',
+        description: 'Optional short heading for the question, such as "Confirm" or "Choose Mode".',
+      },
+      question: {
+        type: 'string',
+        required: true,
+        description: 'The specific question to ask the user.',
+      },
+      options: {
+        type: 'array',
+        description: 'Optional mutually exclusive choices to show the user.',
+        items: {
+          type: 'object',
+          properties: {
+            label: { type: 'string', required: true, description: 'Short user-facing option label.' },
+            value: { type: 'string', description: 'Answer text returned to you if this option is selected. Defaults to label.' },
+            description: { type: 'string', description: 'One sentence explaining the tradeoff or impact.' },
+            recommended: { type: 'boolean', description: 'True for the recommended/default option.' },
+          },
+        },
+      },
+      allow_custom: {
+        type: 'boolean',
+        description: 'Whether the user may type a free-form answer instead of selecting an option. Defaults to true.',
+      },
+    },
+    async execute(args, exec) {
+      const result = await ctx.userInteraction.ask({
+        question: args.question,
+        ...args.header !== undefined ? { header: args.header } : {},
+        ...args.options !== undefined ? { options: args.options } : {},
+        ...args.allow_custom !== undefined ? { allowCustom: args.allow_custom } : {},
+        ...exec.agent !== undefined ? { agent: exec.agent } : {},
+        ...exec.signal !== undefined ? { signal: exec.signal } : {},
+      })
+      return [{ type: 'text', text: result.answer }]
+    },
+  }))
+}

packages/core/tool-ask-user/tests/tool-ask-user.spec.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import UserInteractionService, { type AskUserQuestionRequest } from '@deepseek-ai/dsh-user-interaction'
+import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
+
+interface OptionSchemaShape {
+  properties: {
+    options: {
+      items: {
+        properties: Record<string, { type: string }>
+      }
+    }
+  }
+}
+
+async function setup() {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(toolAskUser)
+  return ctx
+}
+
+describe('ask_user_question tool', () => {
+  it('registers a model-facing tool schema', async () => {
+    const ctx = await setup()
+    const schema = ctx.tools.schemas().find(tool => tool.name === 'ask_user_question')
+
+    expect(schema).toMatchObject({
+      name: 'ask_user_question',
+      parameters: {
+        type: 'object',
+        properties: {
+          question: { type: 'string' },
+          options: { type: 'array' },
+          allow_custom: { type: 'boolean' },
+        },
+        required: ['question'],
+      },
+    })
+    const parameters = schema?.parameters as unknown as OptionSchemaShape
+    expect(parameters.properties.options.items.properties).toMatchObject({
+      description: { type: 'string' },
+      recommended: { type: 'boolean' },
+    })
+    expect(parameters.properties.options.items.properties).not.toHaveProperty('desc')
+  })
+
+  it('asks the registered user-interaction provider and returns the answer text', async () => {
+    const ctx = await setup()
+    const seen: AskUserQuestionRequest[] = []
+    ctx.userInteraction.registerProvider({
+      async ask(request) {
+        seen.push(request)
+        const option = request.options?.[0]
+        return option === undefined ? { answer: 'Use pnpm' } : { answer: 'Use pnpm', option }
+      },
+    })
+
+    const result = await ctx.tools.execute({
+      callId: CallId('ask-1'),
+      name: 'ask_user_question',
+      arguments: {
+        question: 'Which package manager should I use?',
+        options: [{ label: 'pnpm', value: 'Use pnpm', recommended: true }],
+        allow_custom: false,
+      },
+    })
+
+    expect(result).toMatchObject({
+      isError: false,
+      content: [{ type: 'text', text: 'Use pnpm' }],
+    })
+    expect(seen).toMatchObject([{
+      question: 'Which package manager should I use?',
+      options: [{ label: 'pnpm', value: 'Use pnpm', recommended: true }],
+      allowCustom: false,
+    }])
+  })
+
+  it('passes the tool abort signal to the user-interaction request', async () => {
+    const ctx = await setup()
+    const seen: AskUserQuestionRequest[] = []
+    ctx.userInteraction.registerProvider({
+      async ask(request) {
+        seen.push(request)
+        return { answer: 'ok' }
+      },
+    })
+    const controller = new AbortController()
+
+    await ctx.tools.execute({
+      callId: CallId('ask-2'),
+      name: 'ask_user_question',
+      arguments: { question: 'Continue?' },
+      signal: controller.signal,
+    })
+
+    expect(seen[0]?.signal).toBe(controller.signal)
+  })
+
+  it('passes optional header and agent through to the user-interaction request', async () => {
+    const ctx = await setup()
+    const seen: AskUserQuestionRequest[] = []
+    ctx.userInteraction.registerProvider({
+      async ask(request) {
+        seen.push(request)
+        return { answer: 'ok' }
+      },
+    })
+    const agent = { id: 'main' } as unknown as Agent
+
+    const result = await ctx.tools.execute({
+      callId: CallId('ask-3'),
+      name: 'ask_user_question',
+      arguments: { header: 'Confirm', question: 'Continue?' },
+      agent,
+    })
+
+    expect(result.content).toEqual([{ type: 'text', text: 'ok' }])
+    expect(seen[0]).toMatchObject({ header: 'Confirm', agent })
+  })
+
+  it('uses an option label when the selected option has no explicit value', async () => {
+    const ctx = await setup()
+    ctx.userInteraction.registerProvider({
+      async ask(request) {
+        const option = request.options?.[0]
+        if (option === undefined) throw new Error('missing option')
+        return { answer: option.label, option }
+      },
+    })
+
+    const result = await ctx.tools.execute({
+      callId: CallId('ask-4'),
+      name: 'ask_user_question',
+      arguments: {
+        question: 'Pick one',
+        options: [{ label: 'Fallback label' }],
+      },
+    })
+
+    expect(result.content).toEqual([{ type: 'text', text: 'Fallback label' }])
+  })
+
+  it('returns the provider-computed answer even when option metadata is present', async () => {
+    const ctx = await setup()
+    ctx.userInteraction.registerProvider({
+      async ask(request) {
+        const option = request.options?.[0]
+        if (option === undefined) throw new Error('missing option')
+        return { answer: `selected ${option.value}`, option }
+      },
+    })
+
+    const result = await ctx.tools.execute({
+      callId: CallId('ask-5'),
+      name: 'ask_user_question',
+      arguments: {
+        question: 'Pick one',
+        options: [{ label: 'A', value: 'a' }],
+      },
+    })
+
+    expect(result.content).toEqual([{ type: 'text', text: 'selected a' }])
+  })
+
+  it('unregisters the tool when its plugin fiber is disposed', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(UserInteractionService)
+    const fiber = await ctx.plugin(toolAskUser)
+    expect(ctx.tools.get('ask_user_question')).toBeDefined()
+
+    await fiber.dispose()
+
+    expect(ctx.tools.get('ask_user_question')).toBeUndefined()
+  })
+})

packages/core/tool-ask-user/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../agent"
+    },
+    {
+      "path": "../system-prompt"
+    },
+    {
+      "path": "../tools"
+    },
+    {
+      "path": "../user-interaction"
+    }
+  ]
+}