@hachej/boring-workspace 0.1.9 → 0.1.12

package/docs/plans/ASK_USER_QUESTIONS_PLUGIN_SPEC.md

@@ -0,0 +1,322 @@
+# Ask User Questions Plugin Spec
+
+Last updated: 2026-05-08
+
+## Summary
+
+Add a blocking `ask_user` capability for agent sessions that opens a Workspace
+page named **Questions**, renders an agent-generated form, lets the user submit
+answers, and returns those answers to the waiting agent tool call.
+
+The Workspace implementation owns the page/plugin UI, form primitives, and UI
+bridge command handling. The Agent implementation owns the blocking tool runtime
+and session-level waiter. The browser must submit answers through the Workspace
+UI bridge command path, not through ad-hoc form POST semantics.
+
+## Goals
+
+- Provide an agent tool that asks the user for structured input and blocks until
+  the user answers or cancels.
+- Open or focus a Workspace page/panel named `Questions` whenever a question is
+  pending.
+- Render forms from a portable, JSON-serializable schema generated by the agent.
+- Provide primitive React UI components and hooks so app shells can render these
+  forms in a standard way.
+- Persist the single pending question per agent session across browser reloads.
+- Send submitted answers back to the waiting agent through `UiBridge.postCommand`
+  as the single user-dispatch source.
+- Keep Workspace base front/shared code package-neutral; no value imports from
+  `@boring/agent` outside allowed app composition boundaries.
+
+## Non-goals
+
+- Multiple simultaneous pending questions per agent session.
+- File upload fields in the first version.
+- Full process-crash restoration of an already-blocked in-memory tool call,
+  unless the current agent session runtime already supports rehydrating waiters.
+- Using chat-stream `data-ui-command` parts as the source of truth for answers.
+- Making `pi-ask-user` the Workspace UX implementation dependency.
+
+## User flow
+
+1. Agent calls `ask_user` with title, optional context, and form schema.
+2. Server creates a pending question record for the current agent session.
+3. Agent tool blocks on an `AskUserCoordinator` waiter.
+4. Workspace receives/loads the pending question and opens or focuses the
+   `Questions` page.
+5. User fills the form and clicks Submit.
+6. Questions page calls `uiBridge.postCommand({ type: "questions.submit", ... })`.
+7. Workspace bridge server handler validates the command and records the answer.
+8. `AskUserCoordinator` resolves the waiter.
+9. Tool returns the structured answer to the agent and the agent continues.
+
+Cancel follows the same path with `type: "questions.cancel"` and returns a
+stable cancelled result to the tool caller.
+
+## Package placement
+
+### `@boring/workspace/shared`
+
+Define browser-safe contracts only:
+
+- `AskUserQuestion`
+- `AskUserFormSchema`
+- `AskUserField`
+- `AskUserAnswer`
+- `QuestionsSubmitCommand`
+- `QuestionsCancelCommand`
+- stable error codes imported from the canonical error-code enum
+
+No `node:*`, no `Buffer`, no `@boring/agent` value imports.
+
+### `@boring/workspace/plugins/questionsPlugin`
+
+New default Workspace plugin that owns:
+
+- `front/QuestionsPage.tsx`
+- `front/QuestionsPanel.tsx`
+- `front/usePendingQuestion.ts`
+- `front/primitives/QuestionForm.tsx`
+- `front/primitives/QuestionField.tsx`
+- field primitive components
+- `server/questionsBridge.ts`
+- `shared/types.ts`
+
+Plugin outputs should include at minimum:
+
+- a panel/page output for `Questions`
+- a command output or bridge binding for `questions.submit`
+- a command output or bridge binding for `questions.cancel`
+- a surface resolver if the workspace opens the page through `openSurface`
+
+### `@boring/workspace/app/*`
+
+App composition may wire the questions plugin to `@boring/agent/server` tool
+registration APIs. This is the allowed boundary for Workspace + Agent product
+composition.
+
+### `@boring/agent/server`
+
+Agent package should expose the blocking `ask_user` tool factory and an adapter
+interface that Workspace can satisfy:
+
+```ts
+interface AskUserRuntime {
+  askUser(request: AskUserRequest): Promise<AskUserToolResult>
+}
+```
+
+Workspace app/server composition injects a runtime that stores the pending
+question and resolves through UI bridge answers.
+
+## Form schema
+
+Use a small JSON-schema-lite contract. It is serializable, easy to render in
+React, and avoids forcing Zod or another runtime validator across the shared
+browser/server boundary. A later helper may compile from Zod or JSON Schema into
+this format.
+
+```ts
+type AskUserFormSchema = {
+  fields: AskUserField[]
+  submitLabel?: string
+}
+
+type AskUserField =
+  | {
+      type: "text"
+      name: string
+      label: string
+      required?: boolean
+      placeholder?: string
+      defaultValue?: string
+      helpText?: string
+    }
+  | {
+      type: "textarea"
+      name: string
+      label: string
+      required?: boolean
+      placeholder?: string
+      defaultValue?: string
+      helpText?: string
+    }
+  | {
+      type: "select"
+      name: string
+      label: string
+      required?: boolean
+      options: AskUserOption[]
+      defaultValue?: string
+      helpText?: string
+    }
+  | {
+      type: "multiselect"
+      name: string
+      label: string
+      required?: boolean
+      options: AskUserOption[]
+      defaultValue?: string[]
+      helpText?: string
+    }
+  | {
+      type: "checkbox"
+      name: string
+      label: string
+      defaultValue?: boolean
+      helpText?: string
+    }
+  | {
+      type: "radio"
+      name: string
+      label: string
+      required?: boolean
+      options: AskUserOption[]
+      defaultValue?: string
+      helpText?: string
+    }
+
+type AskUserOption = {
+  value: string
+  label: string
+  description?: string
+}
+```
+
+Answer shape:
+
+```ts
+type AskUserAnswer = {
+  questionId: string
+  sessionId: string
+  values: Record<string, string | string[] | boolean | null>
+  submittedAt: string
+}
+```
+
+Tool result shape:
+
+```ts
+type AskUserToolResult =
+  | { status: "answered"; answer: AskUserAnswer }
+  | { status: "cancelled"; questionId: string; sessionId: string }
+```
+
+## Persistence
+
+Only one pending question is allowed per agent session. Creating a new pending
+question for a session that already has one should fail with a stable error code
+or replace only if an explicit future `replacePending` option is added.
+
+Store interface:
+
+```ts
+interface AskUserStore {
+  getPending(sessionId: string): Promise<AskUserQuestion | null>
+  createPending(question: AskUserQuestion): Promise<void>
+  answer(questionId: string, answer: AskUserAnswer): Promise<void>
+  cancel(questionId: string): Promise<void>
+  clearPending(sessionId: string): Promise<void>
+}
+```
+
+Initial implementation should provide a file-backed or existing workspace-store
+adapter. Core/cloud can later inject a DB-backed implementation.
+
+Persistence requirement for v1: pending question survives browser reload and the
+Questions page can re-render it. Full server-process crash resumption of the
+blocked tool waiter is a later concern unless already provided by the current
+agent session runtime.
+
+## UI bridge commands
+
+The browser submits through `UiBridge.postCommand`:
+
+```ts
+uiBridge.postCommand({
+  type: "questions.submit",
+  questionId,
+  sessionId,
+  values,
+})
+```
+
+Cancel:
+
+```ts
+uiBridge.postCommand({
+  type: "questions.cancel",
+  questionId,
+  sessionId,
+})
+```
+
+Server bridge handlers must:
+
+- validate `sessionId` and `questionId`
+- validate submitted values against the form schema
+- persist answer/cancel state
+- resolve the matching `AskUserCoordinator` waiter
+- emit/update Workspace state so the Questions page leaves pending mode
+
+No direct browser form route should be treated as the conceptual API. If an HTTP
+route exists underneath, it is only transport for the UI bridge.
+
+## Questions page behavior
+
+- Register/open a page or panel titled `Questions`.
+- Auto-open or focus when a new pending question appears.
+- Show title, context, form fields, submit button, and cancel affordance.
+- Disable submit while validation fails or command is in flight.
+- After submit, show a short answered state and return focus behavior to the
+  workspace shell if appropriate.
+- If no pending question exists, show an empty state: "No questions right now."
+
+## Primitive UI package
+
+Expose primitives from Workspace front code so apps can customize the page while
+keeping standard schema behavior:
+
+- `<QuestionForm schema values onValuesChange onSubmit onCancel />`
+- `<QuestionField field value onChange error />`
+- `<QuestionSubmitButton />`
+- `<QuestionCancelButton />`
+- `useQuestionForm(schema, initialValues?)`
+- `validateQuestionValues(schema, values)`
+
+Primitives should be headless-enough to style, but the default Questions page
+should provide a polished complete UI.
+
+## `pi-ask-user` evaluation
+
+`pi-ask-user` provides a native Pi `ask_user` tool with TUI overlay/inline UI,
+selection lists, freeform input, multi-select, timeout, and a useful bundled
+skill. It is good prior art and may be useful as a standalone CLI fallback.
+
+Do not make it the primary Workspace implementation because it does not provide:
+
+- Workspace page/panel integration
+- generated rich React form rendering
+- Workspace persistence semantics
+- answer dispatch through `UiBridge.postCommand`
+- app-shell primitive components
+
+Recommended stance:
+
+- Use `pi-ask-user` as reference for prompt/tool ergonomics.
+- Consider optional CLI/TUI fallback for standalone `@boring/agent` mode.
+- Keep Workspace Questions plugin implementation first-party.
+
+## Acceptance criteria for implementation bead
+
+- Shared schema/types exist and are browser-safe.
+- Questions plugin registers a `Questions` page/panel.
+- Agent/session can create one pending question and block for the answer.
+- Pending question persists across browser reload.
+- Default page renders text, textarea, select, multiselect, checkbox, and radio.
+- Submit uses `UiBridge.postCommand`, not direct conceptual route dispatch.
+- Submitted values resolve the blocking tool call.
+- Cancel resolves the tool call with `status: "cancelled"`.
+- Primitive form components/hooks are exported for app-shell reuse.
+- Unit tests cover schema validation and one-pending-question enforcement.
+- Integration test or harness test covers ask -> render -> submit -> tool result.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-workspace",
-  "version": "0.1.9",
+  "version": "0.1.12",
   "type": "module",
   "license": "MIT",
   "description": "Workspace UI, plugin, and bridge package for composing chat, files, catalogs, editors, and app-specific panes.",
@@ -125,8 +125,8 @@
     "tailwind-merge": "^2.0.0",
     "zod": "^3.23.0",
     "zustand": "^5.0.0",
-    "@hachej/boring-agent": "0.1.9",
-    "@hachej/boring-ui-kit": "0.1.9"
+    "@hachej/boring-agent": "0.1.12",
+    "@hachej/boring-ui-kit": "0.1.12"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.0.0",