clarifyingLlmPlanner

clarifyingLlmPlanner(options): Stage<ClarifyingLlmPlannerInput, PlannerOutput>

Defined in: packages/planner-llm/src/lib/llm-planner.ts:182

A planner that honours the request’s skipReply flag and may answer with a needs-clarification result. It returns the skipReply arm of the protocol’s PlannerOutputFor: a tagged plan without userMessage, or a NeedsClarification.

Without the flag, or with skipReply: false, it behaves exactly like llmPlanner: the same system prompt, user prompt, structured output schema and tagged, reply-bearing candidate.

With skipReply: true it sends a system prompt that never asks for a reply and a structured output schema without userMessage but with an optional clarification (a question and optional options). Output without a clarification is returned as a plan tagged type: 'plan' with no userMessage key. Output with one is returned as a NeedsClarification whose layout and executionPlan are the partial changes the model filled for the parts of the request that are already clear. When the model returns an empty executionPlan and the request’s current layout, the clarification carries neither. A request the planner cannot fulfil comes back as a clarification that names the gap and offers the closest supported options.

Clarification partial changes are not validated on the withRetry path: withRetry returns a clarification without validating or retrying it. The Engine validates them when it handles the request.

The user prompt, hints, enum snapshot reuse, retry prompt, instrumentation and error mapping are those of llmPlanner; on a retry the system prompt and schema stay those of the request’s mode and flag.

Parameters

options

LlmPlannerOptions

Returns

Stage<ClarifyingLlmPlannerInput, PlannerOutput>

Throws

If options is invalid or a system-prompt customizer is misconfigured. The default and reply-free system prompts for both layout modes are built once here, so the error surfaces at construction. The message starts with Invalid LlmPlannerOptions: and the original error is attached as cause.

Example

const engine = createEngine({
  planner: withRetry(clarifyingLlmPlanner({ adapter: openaiText('gpt-4o') }), {
    max: 1,
  }),
});