u

src/tools/ask-user.js

@@ -0,0 +1,43 @@
+import { defineTool, DirectReturnError } from 'libllmorbiter';
+
+/**
+ * ask_user tool:
+ * Allows the LLM to ask the user for clarification or a decision (e.g. which SKU or ID
+ * they meant, or what parameter to use).
+ *
+ * When invoked, it raises a DirectReturnError with recordResult: false so the LLMOrbiter
+ * halts the inference loop immediately without generating a synthetic tool response.
+ * The conversation transitions into `idle` state, allowing the client/user to submit
+ * a tool response via the API.
+ */
+export function createAskUserTool() {
+    return defineTool({
+        name: 'ask_user',
+        description:
+            'Ask the user when you need clarification or a decision (e.g. which SKU or ID they meant, or what parameter to use). ' +
+            'Give a concise question + up to 3 short options (A,B,C); the user may select an option or provide free-form text.',
+        strict: false,
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['question'],
+            properties: {
+                question: {
+                    type: 'string',
+                    description: 'Question for the user.',
+                },
+                options: {
+                    type: 'array',
+                    description: 'Up to 3 short option labels.',
+                    items: { type: 'string' },
+                    maxItems: 3,
+                },
+            },
+        },
+        invoke: async ({ question, options = [] }) => {
+            const capped = Array.isArray(options) ? options.slice(0, 3) : [];
+            // Stop LLM loop immediately so the conversation stays idle awaiting user tool response
+            throw new DirectReturnError({ question, options: capped }, { recordResult: false });
+        },
+    });
+}