import { getContext, getRequestLogger } from "@obs/context"; import type { AgentRequest } from "@agent/types"; import type { LlmClient } from "@llm/llm-client"; import type { ChatMessage } from "@llm/types"; import type { Tool, ToolContext } from "@tools/tool"; import { getAgentCriticMaxIterations, getAgentProgrammaticToolCalling, getLlmTemperature, getPlannerMaxTokens, getTier0EstimatedCallMs, getTier0MaxTokens, getTier0Model, getTier1EstimatedCallMs, getTier1MaxTokens, getTier1PlannerModel, getTier1ResponderModel, getTier2EstimatedCallMs, getTier2MaxTokens, } from "../../../config.js"; import type { DerivedState } from "../state/onboarding-state.js"; import { buildSkillResourceAddendum } from "../prompts/builder.js"; import { OnboardingCritic } from "./critic.js"; import type { PlannerOutput } from "./planner-schema.js"; import { PlannerOutputSchema } from "./planner-schema.js"; import { getActiveProcessTrace } from "./trace.js"; import { runToolPlan, type ToolPlanResult } from "./tool-plan-runner.js"; import { runWithTools } from "./tool-loop.js"; export interface OrchestratorRunOptions { maxTokens?: number | undefined; request?: AgentRequest | undefined; temperature?: number | undefined; toolContext: ToolContext; tools?: readonly Tool[] | undefined; } function cloneMessages(messages: ChatMessage[]): ChatMessage[] { return messages.map((message) => ({ ...message, tool_calls: message.tool_calls ? [...message.tool_calls] : undefined, })); } function injectSystemAddendum( messages: ChatMessage[], addendum: string, ): ChatMessage[] { const cloned = cloneMessages(messages); const firstSystemIndex = cloned.findIndex((message) => message.role === "system"); if (firstSystemIndex === -1) { cloned.unshift({ role: "system", content: addendum, }); return cloned; } const current = cloned[firstSystemIndex]; if (!current) { return cloned; } cloned[firstSystemIndex] = { ...current, content: `${current.content}\n\n${addendum}`, }; return cloned; } function summarizeMessages(messages: ChatMessage[]): string { return messages .map((message) => `[${message.role}] ${message.content}`) .join("\n\n"); } function tryParsePlannerOutput(raw: string): PlannerOutput | null { try { const parsed = JSON.parse(raw) as unknown; return PlannerOutputSchema.parse(parsed); } catch { const start = raw.indexOf("{"); const end = raw.lastIndexOf("}"); if (start === -1 || end === -1 || end <= start) { return null; } try { const parsed = JSON.parse(raw.slice(start, end + 1)) as unknown; return PlannerOutputSchema.parse(parsed); } catch { return null; } } } function getDefaultPlan(derived: DerivedState): PlannerOutput { return { approach: derived.responseMode === "llm-with-tools" ? "validate-then-explain" : derived.intent.kind === "help-how" || derived.intent.kind === "help-where" ? "redirect-to-step" : "answer-direct", targetPhase: derived.phase.kind, mustInclude: [], mustAvoid: [], requestResources: [], suggestedTools: derived.responseMode === "llm-with-tools" ? ["validate-nickname"] : [], tone: derived.allowShortResponse ? "concise" : "friendly", targetLengthChars: derived.allowShortResponse ? 80 : 150, rationale: "fallback-plan", }; } function getRemainingDeadlineMs(): number | undefined { const deadlineAt = getContext()?.deadlineAt; if (!deadlineAt) { return undefined; } const deadlineMs = Date.parse(deadlineAt) - Date.now(); return Number.isFinite(deadlineMs) ? deadlineMs : undefined; } function canAffordCall(estimatedCallMs: number): boolean { const remainingMs = getRemainingDeadlineMs(); return remainingMs === undefined || remainingMs > estimatedCallMs; } function buildPlannerMessages( derived: DerivedState, messages: ChatMessage[], ): ChatMessage[] { return [ { role: "system", content: [ "당신은 온보딩 응답을 설계하는 planner입니다.", "반드시 JSON만 출력하세요.", "질문에 직접 답할 수 있으면 answer-direct를 우선하고, 유저가 묻지 않은 추가 절차는 mustAvoid에 넣으세요.", "tool은 꼭 필요한 경우에만 suggestedTools에 넣고 최대 3개까지만 고르세요.", ].join("\n"), }, { role: "user", content: [ `[STATE] intent=${derived.intent.kind}, phase=${derived.phase.kind}, responseMode=${derived.responseMode}, tier=${derived.tier}`, "[CONVERSATION]", summarizeMessages(messages), "[SCHEMA]", JSON.stringify({ approach: "answer-direct | ask-clarification | redirect-to-step | validate-then-explain | lookup-rule-then-answer | soft-decline", targetPhase: "fresh | nickname-pending | photo-pending | both-pending | step1-completed | nickname-rejected | photo-rejected | deadline-near | completed | timed-out", mustInclude: ["short strings"], mustAvoid: ["short strings"], suggestedTools: [ "validate-nickname | check-onboarding-progress | lookup-community-rule | get-room-context | verify-discord-nickname", ], requestResources: [ "nickname-format | heart-rule | discord-format | age-policy", ], toolPlan: { composeWith: "all-then-llm", steps: [ { id: "step-id", tool: "validate-nickname", argsLiteral: { nickname: "value" }, argsFromContext: { chatroomId: "$request.chatroomId" }, dependsOn: [], on: { error: "fallback-llm" }, }, ], }, tone: "friendly | concise | encouraging | neutral | apologetic", targetLengthChars: 150, rationale: "short reason", }), ].join("\n\n"), }, ]; } function buildResponderAddendum(plan: PlannerOutput): string { const lines = [ "[PLAN]", `approach=${plan.approach}`, `tone=${plan.tone}`, `targetLengthChars=${plan.targetLengthChars}`, ]; if (plan.targetPhase) { lines.push(`targetPhase=${plan.targetPhase}`); } lines.push( `mustInclude=${plan.mustInclude.length > 0 ? plan.mustInclude.join(" | ") : "-"}`, `mustAvoid=${plan.mustAvoid.length > 0 ? plan.mustAvoid.join(" | ") : "-"}`, "위 계획을 참고하되, 실제 유저에게 보낼 최종 한국어 답변만 출력하세요.", ); return lines.join("\n"); } function buildToolPlanAddendum(result: ToolPlanResult): string { return [ "[TOOL_PLAN_RESULTS]", JSON.stringify({ durationMs: result.durationMs, failures: result.failures.map((failure) => ({ kind: failure.kind, message: failure.message, retryable: failure.retryable, toolName: failure.toolName, })), results: result.results, }), "위 toolPlan 결과를 사실 정보로 사용하고, 실패한 도구 결과는 추측으로 메우지 마세요.", ].join("\n"); } function pickToolsForPlan( plan: PlannerOutput, tools: readonly Tool[], forceTools: boolean, ): readonly Tool[] { if (!forceTools && (plan.approach === "answer-direct" || plan.approach === "soft-decline")) { return []; } if (plan.suggestedTools.length === 0) { return tools; } const picked = tools.filter((tool) => plan.suggestedTools.includes(tool.name as never)); return picked.length > 0 ? picked : tools; } export class OnboardingOrchestrator { private readonly critic: OnboardingCritic; constructor(private readonly llmClient: LlmClient) { this.critic = new OnboardingCritic(llmClient); } private async runDirect( derived: DerivedState, messages: ChatMessage[], options: OrchestratorRunOptions, responderTools: readonly Tool[], maxTokens: number, modelOverride: string, ): Promise { const logger = getRequestLogger(); const deadlineMs = getRemainingDeadlineMs(); logger.debug( { intent: derived.intent.kind, responderTools: responderTools.map((tool) => tool.name), role: "responder", tier: derived.tier, }, "[OnboardingOrchestrator] Responder execution mode decided", ); if (responderTools.length > 0) { return runWithTools({ deadlineMs, llmClient: this.llmClient, maxTokens, messages, modelOverride, role: "responder", routingDecision: derived.routingDecision, tier: derived.tier, temperature: options.temperature ?? getLlmTemperature(), toolContext: options.toolContext, tools: responderTools, }); } const response = await this.llmClient.chatCompletion(messages, { deadlineMs, maxTokens, modelOverride, role: "responder", routingDecision: derived.routingDecision, temperature: options.temperature ?? getLlmTemperature(), tier: derived.tier, }); return response?.content ?? null; } private async runPlanner( derived: DerivedState, messages: ChatMessage[], ): Promise { const logger = getRequestLogger(); const traceStep = getActiveProcessTrace()?.startStep("plan"); const finishTrace = (plan: PlannerOutput): PlannerOutput => { traceStep?.finish({ approach: plan.approach, mustAvoid: plan.mustAvoid, mustInclude: plan.mustInclude, requestResources: plan.requestResources, suggestedTools: plan.suggestedTools, targetLengthChars: plan.targetLengthChars, toolPlanStepCount: plan.toolPlan?.steps.length, }); return plan; }; const plannerMessages = buildPlannerMessages(derived, messages); const firstAttempt = await this.llmClient.chatCompletion(plannerMessages, { deadlineMs: getRemainingDeadlineMs(), jsonMode: true, maxTokens: getPlannerMaxTokens(), modelOverride: getTier1PlannerModel(), role: "planner", routingDecision: derived.routingDecision, temperature: 0, tier: 1, }); const firstPlan = firstAttempt?.content ? tryParsePlannerOutput(firstAttempt.content) : null; if (firstPlan) { logger.debug( { intent: derived.intent.kind, plan: firstPlan, source: "first-attempt", }, "[OnboardingOrchestrator] Planner output parsed", ); return finishTrace(firstPlan); } const retryMessages = [ ...plannerMessages, { role: "user" as const, content: "방금 응답은 스키마를 벗어났어요. 설명 없이 JSON object 하나만 다시 출력하세요.", }, ]; const retry = await this.llmClient.chatCompletion(retryMessages, { deadlineMs: getRemainingDeadlineMs(), jsonMode: true, maxTokens: getPlannerMaxTokens(), modelOverride: getTier1PlannerModel(), role: "planner", routingDecision: derived.routingDecision, temperature: 0, tier: 1, }); const retryPlan = retry?.content ? tryParsePlannerOutput(retry.content) : null; if (retryPlan) { logger.debug( { intent: derived.intent.kind, plan: retryPlan, source: "retry", }, "[OnboardingOrchestrator] Planner output parsed", ); return finishTrace(retryPlan); } const fallbackPlan = getDefaultPlan(derived); logger.debug( { intent: derived.intent.kind, plan: fallbackPlan, source: "fallback", }, "[OnboardingOrchestrator] Planner fell back to default plan", ); return finishTrace(fallbackPlan); } private async runTier0( derived: DerivedState, messages: ChatMessage[], options: OrchestratorRunOptions, ): Promise { const maxTokens = options.maxTokens ?? getTier0MaxTokens(); const tools = derived.responseMode === "llm-with-tools" ? (options.tools ?? []) : []; return this.runDirect( derived, messages, options, tools, maxTokens, getTier0Model(), ); } private async runTier1( derived: DerivedState, messages: ChatMessage[], options: OrchestratorRunOptions, ): Promise { const plan = await this.runPlanner(derived, messages); const responderMessages = injectSystemAddendum( messages, buildResponderAddendum(plan), ); const forceTools = derived.responseMode === "llm-with-tools"; let finalResponderMessages = responderMessages; let responderTools = pickToolsForPlan(plan, options.tools ?? [], forceTools); const resourceAddendum = buildSkillResourceAddendum(plan.requestResources); if (resourceAddendum) { finalResponderMessages = injectSystemAddendum( finalResponderMessages, resourceAddendum, ); } const toolPlanResult = await this.runProgrammaticToolPlan( plan, finalResponderMessages, options, ); if (toolPlanResult && !toolPlanResult.fallbackToLlm) { finalResponderMessages = injectSystemAddendum( finalResponderMessages, buildToolPlanAddendum(toolPlanResult), ); responderTools = []; } return this.runDirect( derived, finalResponderMessages, options, responderTools, options.maxTokens ?? getTier1MaxTokens(), getTier1ResponderModel(), ); } private async runTier2( derived: DerivedState, messages: ChatMessage[], options: OrchestratorRunOptions, ): Promise { const plan = await this.runPlanner(derived, messages); const responderMessages = injectSystemAddendum( messages, buildResponderAddendum(plan), ); const forceTools = derived.responseMode === "llm-with-tools"; let finalResponderMessages = responderMessages; let responderTools = pickToolsForPlan(plan, options.tools ?? [], forceTools); const resourceAddendum = buildSkillResourceAddendum(plan.requestResources); if (resourceAddendum) { finalResponderMessages = injectSystemAddendum( finalResponderMessages, resourceAddendum, ); } const toolPlanResult = await this.runProgrammaticToolPlan( plan, finalResponderMessages, options, ); if (toolPlanResult && !toolPlanResult.fallbackToLlm) { finalResponderMessages = injectSystemAddendum( finalResponderMessages, buildToolPlanAddendum(toolPlanResult), ); responderTools = []; } const draft = await this.runDirect( derived, finalResponderMessages, options, responderTools, options.maxTokens ?? getTier2MaxTokens(), getTier1ResponderModel(), ); if (!draft) { return null; } const maxIterations = getAgentCriticMaxIterations(); const critique = maxIterations > 1 ? await this.critic.critiqueIterative( draft, derived, finalResponderMessages, { deadlineMs: getRemainingDeadlineMs(), maxIterations, }, ) : await this.critic.critique(draft, derived, finalResponderMessages, { deadlineMs: getRemainingDeadlineMs(), }); return critique.text; } private async runProgrammaticToolPlan( plan: PlannerOutput, _messages: ChatMessage[], options: OrchestratorRunOptions, ): Promise { if ( !getAgentProgrammaticToolCalling() || !plan.toolPlan || !options.request || !options.tools?.length ) { return null; } return runToolPlan( plan.toolPlan, options.tools, options.toolContext, options.request, ); } async run( derived: DerivedState, messages: ChatMessage[], options: OrchestratorRunOptions, ): Promise { if (derived.tier >= 2 && canAffordCall(getTier2EstimatedCallMs())) { return this.runTier2(derived, messages, options); } if (derived.tier >= 1 && canAffordCall(getTier1EstimatedCallMs())) { return this.runTier1(derived, messages, options); } if (!canAffordCall(getTier0EstimatedCallMs())) { return null; } return this.runTier0(derived, messages, options); } }