import type { AgentRequest, AgentResponse, ConversationMessage } from "@agent/types"; import { getConversationSummaryKey } from "@conv/conversation-store"; import type { GarnetClient } from "@common/garnet"; import { getContext, getRequestLogger } from "@obs/context"; import type { LlmClient } from "@llm/llm-client"; import type { ChatMessage } from "@llm/types"; import type { RoomContextService } from "@room/room-context-service"; import type { Skill } from "@skills/skill"; import { type ShadowEvalPublisher, ShadowEvalBus, } from "@eval/shadow-bus"; import { createBuiltInToolRegistry } from "@tools/builtins/index"; import type { Tool, ToolContext } from "@tools/tool"; import { PromptBuilder } from "./prompts/builder.js"; import { getAcknowledgementMessage, getAgeRequirementMessage, getCompletedMessage, getDiscordMessage, getGreetingMessage, getGenericHelpMessage, getHeartGuideMessage, getHeartLocationMessage, getNicknameInvalidMessage, getNicknameFormatMessage, getPhotoFailedMessage, getProgressMessage, getRemainingStatusMessage, getTimeoutWarningMessage, } from "./onboarding-templates.js"; import { getOnboardingSessionKeyPrefix, getLlmTemperature } from "../../config.js"; import { OnboardingBlackboardStore } from "./state/blackboard.js"; import { deriveState } from "./state/derive.js"; import { OnboardingIntentClassifier } from "./state/classifier.js"; import type { DerivedState, Intent } from "./state/onboarding-state.js"; import { OnboardingOrchestrator } from "./runtime/orchestrator.js"; import { validateOnboardingResponse } from "./runtime/validator.js"; import type { OnboardingSession, PromptContext } from "./types.js"; type LlmTextResult = | { status: "success"; text: string } | { status: "no_response" } | { status: "failed" }; export class OnboardingSkill implements Skill { readonly name = "onboarding"; private readonly classifier: OnboardingIntentClassifier; private readonly blackboardStore: OnboardingBlackboardStore; private readonly orchestrator: OnboardingOrchestrator; private readonly shadowEvalPublisher: ShadowEvalPublisher; private readonly tools: readonly Tool[]; constructor( private readonly garnetClient: GarnetClient, private readonly llmClient: LlmClient, private readonly roomContextService?: RoomContextService, shadowEvalPublisher?: ShadowEvalPublisher, ) { this.classifier = new OnboardingIntentClassifier(llmClient); this.blackboardStore = new OnboardingBlackboardStore(garnetClient); this.orchestrator = new OnboardingOrchestrator(llmClient); this.shadowEvalPublisher = shadowEvalPublisher ?? new ShadowEvalBus(garnetClient); this.tools = createBuiltInToolRegistry().list(); } canHandle(request: AgentRequest): boolean { return request.skill === "onboarding"; } async handle( request: AgentRequest, conversationHistory: ConversationMessage[], ): Promise { const logger = getRequestLogger(); const session = await this.loadSession( request.chatroomId, request.userId, ); if (request.trigger === "user-message" && !request.userMessage?.trim()) { return this.makeEmptyResponse(request.requestId); } const classified = await this.classifier.classify( request.userMessage, request.trigger, ); const derived = deriveState(session, request.trigger, classified.intent); if (!derived.shouldRespond) { return this.makeEmptyResponse(request.requestId); } let response: AgentResponse; if (derived.responseMode === "template") { response = this.makeTemplateFallbackResponse( request, session, derived.intent, derived, ); } else { const llmResult = await this.handleLlm( request, session, conversationHistory, derived, ); if (llmResult.status === "success") { response = this.makeLlmResponse(request.requestId, llmResult.text); } else if (llmResult.status === "no_response") { response = this.makeEmptyResponse(request.requestId); } else { response = this.makeTemplateFallbackResponse( request, session, derived.intent, derived, ); } } if (response.text.trim()) { await this.rememberTurn(request, derived).catch((error) => { logger.warn({ err: error }, "[OnboardingSkill] Failed to update blackboard"); }); this.shadowEvalPublisher.publish({ classified, createdAt: new Date().toISOString(), derived, latencyMs: this.getCurrentLatencyMs(), request, response, }); } return response; } private async loadSession( chatroomId: string, userId: string, ): Promise { const prefix = getOnboardingSessionKeyPrefix(); const key = `${prefix}:onboarding:${chatroomId}:${userId}`; return this.garnetClient.getJson(key); } private async handleLlm( request: AgentRequest, session: OnboardingSession | null, conversationHistory: ConversationMessage[], derived: DerivedState, ): Promise { const messages = await this.buildLlmMessages( request, session, conversationHistory, derived, ); return this.generateLlmText(messages, derived, { allowShortResponse: derived.allowShortResponse, maxTokens: derived.suggestedMaxTokens, retryOnLowQuality: request.trigger === "user-message" && !derived.allowShortResponse && derived.responseMode !== "llm-with-tools", toolContext: this.buildToolContext(request, session), tools: this.selectToolsForDerived(derived), }); } private async buildLlmMessages( request: AgentRequest, session: OnboardingSession | null, conversationHistory: ConversationMessage[], derived: DerivedState, ): Promise { const logger = getRequestLogger(); const roomContextPromise = request.trigger === "user-message" && this.roomContextService ? this.roomContextService .getRecentMessages(request.chatroomId) .catch((error) => { logger.warn({ err: error }, "[OnboardingSkill] Failed to fetch room context"); return undefined; }) : Promise.resolve(undefined); const [blackboard, summary, roomContext] = await Promise.all([ this.blackboardStore.load(request.chatroomId, request.userId), this.loadConversationSummary(request.chatroomId, request.userId), roomContextPromise, ]); const context: PromptContext = { blackboard, conversationHistory, roomContext, summary, userMessage: this.buildPromptUserMessage(request, derived), }; return PromptBuilder.forDerived(derived, session, context).build(); } private buildPromptUserMessage( request: AgentRequest, derived: DerivedState, ): string { switch (request.trigger) { case "nickname-invalid": return `현재 닉네임은 "${request.nickname}"예요. 왜 안 되는지와 어디를 고치면 되는지만 알려줘.`; case "photo-failed": return "하트 인증 사진이 실패했어요. 다시 시도할 수 있게 필요한 내용만 안내해줘."; case "progress-update": return "현재 새내기 등록 진행상황만 짧게 알려줘."; case "timeout-warning": return "등록 마감이 가까워졌어요. 남은 절차만 짧고 따뜻하게 안내해줘."; case "completed": return "새내기 등록을 모두 마친 유저에게 짧고 따뜻하게 축하 인사를 해줘."; case "user-message": if (derived.intent.kind === "status-question") { return "현재 남은 절차나 완료 상태만 1문장으로 아주 짧게 알려줘."; } return request.userMessage?.trim() || "지금 필요한 온보딩 안내만 도와줘."; default: return "지금 필요한 온보딩 안내만 짧게 도와줘."; } } private async loadConversationSummary( chatroomId: string, userId: string, ): Promise { const key = getConversationSummaryKey(chatroomId, userId); return (await this.garnetClient.getString(key)) ?? undefined; } private async rememberTurn( request: AgentRequest, derived: DerivedState, ): Promise { const now = new Date().toISOString(); const userMessage = request.userMessage?.trim(); await this.blackboardStore.update( request.chatroomId, request.userId, (current) => { const openQuestions = userMessage && ( derived.intent.kind === "help-how" || derived.intent.kind === "help-where" || derived.intent.kind === "nickname-question" || derived.intent.kind === "photo-question" || derived.intent.kind === "discord-question" ) ? [...current.openQuestions, userMessage].slice(-3) : current.openQuestions; const recentNicknameAttempts = request.trigger === "nickname-invalid" || derived.intent.kind === "nickname-question" ? Array.from( new Set([ ...current.recentNicknameAttempts, request.nickname, ]), ).slice(-5) : current.recentNicknameAttempts; return { ...current, flaggedIssues: derived.phase.kind === "nickname-rejected" ? derived.phase.issues.map((issue) => issue.message) : derived.phase.kind === "completed" ? [] : current.flaggedIssues, lastIntent: derived.intent.kind, lastIntentAt: now, openQuestions: derived.phase.kind === "completed" ? [] : openQuestions, recentNicknameAttempts, toneMemory: { ...current.toneMemory, greetedAt: derived.intent.kind === "greeting" ? now : current.toneMemory.greetedAt, thankedAt: derived.intent.kind === "acknowledgement" ? now : current.toneMemory.thankedAt, }, }; }, ); } private makeTemplateFallbackResponse( request: AgentRequest, session: OnboardingSession | null, intent: Intent, derived: DerivedState, ): AgentResponse { switch (request.trigger) { case "new-member": return this.makeEmptyResponse(request.requestId); case "nickname-invalid": return this.makeTemplateResponse( request.requestId, getNicknameInvalidMessage(request.nickname, session), ); case "photo-failed": return this.makeTemplateResponse( request.requestId, getPhotoFailedMessage(request.nickname), ); case "progress-update": return this.makeTemplateResponse( request.requestId, session ? getProgressMessage(request.nickname, session) : getGenericHelpMessage(request.nickname, session), ); case "timeout-warning": return this.makeTemplateResponse( request.requestId, getTimeoutWarningMessage(request.nickname), ); case "completed": return this.makeTemplateResponse( request.requestId, getCompletedMessage(request.nickname), ); default: return this.makeTemplateResponse( request.requestId, this.getIntentFallbackText(request.nickname, session, intent, derived), ); } } private getIntentFallbackText( nickname: string, session: OnboardingSession | null, intent: Intent, derived: DerivedState, ): string { switch (intent.kind) { case "greeting": return getGreetingMessage(); case "acknowledgement": return getAcknowledgementMessage(); case "status-question": return getRemainingStatusMessage(session); case "nickname-question": return derived.phase.kind === "nickname-rejected" ? getNicknameInvalidMessage(nickname, session) : getNicknameFormatMessage(); case "photo-question": return derived.phase.kind === "photo-rejected" ? getPhotoFailedMessage(nickname) : getHeartGuideMessage(); case "help-where": if ( derived.phase.kind === "photo-pending" || derived.phase.kind === "photo-rejected" || (derived.phase.kind === "deadline-near" && derived.phase.remaining.includes("photo")) ) { return getHeartLocationMessage(); } return getGenericHelpMessage(nickname, session); case "help-how": if ( derived.phase.kind === "nickname-pending" || derived.phase.kind === "nickname-rejected" || (derived.phase.kind === "deadline-near" && derived.phase.remaining.includes("nickname")) ) { return getNicknameFormatMessage(); } if ( derived.phase.kind === "photo-pending" || derived.phase.kind === "photo-rejected" || (derived.phase.kind === "deadline-near" && derived.phase.remaining.includes("photo")) ) { return getHeartGuideMessage(); } return getGenericHelpMessage(nickname, session); case "discord-question": return getDiscordMessage(nickname, session); case "age-question": return getAgeRequirementMessage(); case "chitchat": case "off-topic-to-other": return ""; case "unknown": return getGenericHelpMessage(nickname, session); } } private async generateLlmText( messages: ChatMessage[], derived: DerivedState, options?: { allowShortResponse?: boolean; maxTokens?: number; retryOnLowQuality?: boolean; temperature?: number; toolContext?: ToolContext | undefined; tools?: readonly Tool[] | undefined; }, ): Promise { if (!this.llmClient.hasEndpoints()) { return { status: "failed" }; } const attempts: Array<{ maxTokens?: number; temperature?: number; }> = []; const firstAttempt: { maxTokens?: number; temperature?: number; } = {}; if (options?.maxTokens !== undefined) { firstAttempt.maxTokens = options.maxTokens; } if (options?.temperature !== undefined) { firstAttempt.temperature = options.temperature; } attempts.push(firstAttempt); if (options?.retryOnLowQuality) { const retryAttempt: { maxTokens?: number; temperature?: number; } = { temperature: getLlmTemperature() + 0.1, }; if (options.maxTokens !== undefined) { retryAttempt.maxTokens = options.maxTokens; } attempts.push(retryAttempt); } for (const attempt of attempts) { const requestOptions: { maxTokens?: number; temperature?: number; } = {}; if (attempt.maxTokens !== undefined) { requestOptions.maxTokens = attempt.maxTokens; } if (attempt.temperature !== undefined) { requestOptions.temperature = attempt.temperature; } const toolContext = options?.toolContext ?? {}; const llmText = await this.orchestrator.run( derived, messages, { maxTokens: requestOptions.maxTokens, temperature: requestOptions.temperature, toolContext, tools: options?.tools, }, ); if (!llmText) { continue; } const validation = validateOnboardingResponse( llmText, derived, { allowShortResponse: options?.allowShortResponse, }, ); if (validation.text.includes("[NO_RESPONSE]")) { return { status: "no_response" }; } if (validation.status === "reject") { continue; } return { status: "success", text: validation.text, }; } return { status: "failed" }; } private buildToolContext( request: AgentRequest, session: OnboardingSession | null, ): ToolContext { return { chatroomId: request.chatroomId, userId: request.userId, session, garnetClient: this.garnetClient, roomContextService: this.roomContextService, }; } private selectToolsForDerived( derived: DerivedState, ): readonly Tool[] { if (derived.phase.kind === "nickname-rejected") { return this.tools.filter((tool) => tool.name === "validate-nickname" || tool.name === "lookup-community-rule" || tool.name === "check-onboarding-progress", ); } if (derived.intent.kind === "status-question") { return this.tools.filter((tool) => tool.name === "check-onboarding-progress", ); } return this.tools; } private makeTemplateResponse( requestId: string, text: string, ): AgentResponse { return { requestId, text, confidence: 0.8, source: "template", }; } private makeLlmResponse( requestId: string, text: string, ): AgentResponse { return { requestId, text, confidence: 0.9, source: "llm", }; } private makeEmptyResponse(requestId: string): AgentResponse { return { requestId, text: "", confidence: 0, source: "template", }; } private getCurrentLatencyMs(): number | undefined { const startedAt = getContext()?.startedAt; const startedTimestamp = startedAt ? Date.parse(startedAt) : NaN; if (!Number.isFinite(startedTimestamp)) { return undefined; } return Math.max(0, Date.now() - startedTimestamp); } }