@roj-ai/sdk 0.0.2

package/src/plugins/user-chat/prompts.ts

@@ -0,0 +1,30 @@
+/**
+ * User communication prompt sections for system prompt composition.
+ * Used by agents that communicate directly with users (entry + communicator roles).
+ */
+
+/**
+ * Mandatory user communication instructions.
+ */
+export const USER_COMMUNICATION_SECTION = `## User Communication (MANDATORY)
+
+**Every time you receive a user message, you MUST respond to the user via \`tell_user\` or \`ask_user\` before stopping.** The user is waiting for a response and will see nothing unless you explicitly call a communication tool.
+
+- **Direct response**: If you can answer immediately, call \`tell_user\`.
+- **Delegating work**: If you spawn child agents or start background work, call \`tell_user\` to inform the user what is happening (e.g. "I'm starting work on your request…"). Once the work is done, call \`tell_user\` again with the results.
+- **Need more info**: If you need clarification, call \`ask_user\`.
+
+**Never stop without calling \`tell_user\` or \`ask_user\`.** Silent processing leaves the user with no feedback.`
+
+/**
+ * Structured input preferences for asking questions.
+ */
+export const ASKING_QUESTIONS_SECTION = `## Asking Users Questions
+
+When you need to ask the user multiple questions, **call \`ask_user\` multiple times in a single response** rather than asking one question at a time. The user will receive all questions as a single questionnaire, which is much better UX than being asked one-by-one.
+
+Only ask questions sequentially when a later question depends on the answer to an earlier one.
+
+### Prefer Structured Input Types
+
+When asking questions, prefer \`single_choice\`, \`multi_choice\`, or \`confirm\` over free-text \`text\` input whenever the possible answers are known. Only use \`text\` when the answer is truly open-ended. Structured inputs are faster for users and produce more consistent answers.`

package/src/plugins/user-chat/schema.ts

@@ -0,0 +1,80 @@
+import z from 'zod/v4'
+
+export const chatMessageIdSchema = z.string().brand('ChatMessageId')
+
+export type ChatMessageId = z.infer<typeof chatMessageIdSchema>
+
+export const ChatMessageId = (id: string): ChatMessageId => id as ChatMessageId
+
+export const generateChatMessageId = (seq: number): ChatMessageId => ChatMessageId(`m${seq}`)
+
+/**
+ * Option for ask_user single/multi choice input types.
+ */
+export type AskUserOption = {
+	value: string
+	label: string
+	description?: string
+}
+
+/**
+ * Input type for ask_user tool - defines how the user should respond.
+ */
+export type AskUserInputType =
+	| { type: 'text'; placeholder?: string; multiline?: boolean }
+	| { type: 'single_choice'; options: AskUserOption[] }
+	| {
+		type: 'multi_choice'
+		options: AskUserOption[]
+		minSelect?: number
+		maxSelect?: number
+	}
+	| { type: 'rating'; min: number; max: number; labels?: { min?: string; max?: string } }
+	| { type: 'confirm'; confirmLabel?: string; cancelLabel?: string }
+
+// ============================================================================
+// AskUser - Zod schemas
+// ============================================================================
+
+export const askUserOptionSchema = z.object({
+	value: z.string(),
+	label: z.string(),
+	description: z.string().optional(),
+})
+
+export const askUserInputTypeSchema = z.discriminatedUnion('type', [
+	z.object({
+		type: z.literal('text'),
+		placeholder: z.string().optional(),
+		multiline: z.boolean().optional(),
+	}),
+	z.object({
+		type: z.literal('single_choice'),
+		options: z.array(askUserOptionSchema).min(1),
+	}),
+	z.object({
+		type: z.literal('multi_choice'),
+		options: z.array(askUserOptionSchema).min(1),
+		minSelect: z.number().int().min(0).optional(),
+		maxSelect: z.number().int().min(1).optional(),
+	}),
+	z.object({
+		type: z.literal('rating'),
+		min: z.number().int(),
+		max: z.number().int(),
+		labels: z
+			.object({
+				min: z.string().optional(),
+				max: z.string().optional(),
+			})
+			.optional(),
+	}),
+	z.object({
+		type: z.literal('confirm'),
+		confirmLabel: z.string().optional(),
+		cancelLabel: z.string().optional(),
+	}),
+])
+
+export type AskUserInputTypeSchema = z.infer<typeof askUserInputTypeSchema>
+export type AskUserOptionInput = z.infer<typeof askUserOptionSchema>