Initialize onboarding agent scaffold

This commit is contained in:
dahyeon committed 2026-04-16 13:48:53 -07:00
commit 4294f3c92e
57 files changed
+14388

No files matched your search

+70
View File
@@ -0,0 +1,70 @@
import type { GarnetClient } from "@common/garnet";
import { getBlackboardTtlSeconds } from "../../../config.js";
import type { Blackboard } from "../types.js";
function getBlackboardKey(chatroomId: string, userId: string): string {
return `lolympus-agent:bb:${chatroomId}:${userId}`;
}
function createDefaultBlackboard(): Blackboard {
return {
flaggedIssues: [],
openQuestions: [],
recentNicknameAttempts: [],
toneMemory: {},
};
}
function mergeBlackboard(
current: Blackboard | null,
next: Partial<Blackboard>,
): Blackboard {
const base = current ?? createDefaultBlackboard();
return {
flaggedIssues: next.flaggedIssues ?? base.flaggedIssues,
lastIntent: next.lastIntent ?? base.lastIntent,
lastIntentAt: next.lastIntentAt ?? base.lastIntentAt,
openQuestions: next.openQuestions ?? base.openQuestions,
recentNicknameAttempts:
next.recentNicknameAttempts ?? base.recentNicknameAttempts,
toneMemory: {
...base.toneMemory,
...next.toneMemory,
},
};
}
export class OnboardingBlackboardStore {
constructor(private readonly garnetClient: GarnetClient) {}
async load(chatroomId: string, userId: string): Promise<Blackboard> {
const key = getBlackboardKey(chatroomId, userId);
const saved = await this.garnetClient.getJson<Blackboard>(key);
return mergeBlackboard(saved, {});
}
async save(
chatroomId: string,
userId: string,
value: Blackboard,
): Promise<void> {
const key = getBlackboardKey(chatroomId, userId);
await this.garnetClient.setJson(
key,
value,
getBlackboardTtlSeconds(),
);
}
async update(
chatroomId: string,
userId: string,
updater: (current: Blackboard) => Blackboard,
): Promise<Blackboard> {
const current = await this.load(chatroomId, userId);
const next = updater(current);
await this.save(chatroomId, userId, next);
return next;
}
}
@@ -0,0 +1,36 @@
import { describe, expect, it } from "vitest";
import { OnboardingIntentClassifier } from "./classifier.js";
const llmClientStub = {
chatCompletion: () => Promise.resolve(null),
hasEndpoints: () => false,
};
describe("OnboardingIntentClassifier", () => {
const classifier = new OnboardingIntentClassifier(
llmClientStub as never,
);
it("classifies greeting via regex", async () => {
const result = await classifier.classify("안녕하세요", "user-message");
expect(result.intent.kind).toBe("greeting");
expect(result.source).toBe("regex");
});
it("classifies status question via regex", async () => {
const result = await classifier.classify("이제 뭐 남았지", "user-message");
expect(result.intent.kind).toBe("status-question");
});
it("classifies mention as off-topic-to-other", async () => {
const result = await classifier.classify("@프리리 이거 뭐야", "user-message");
expect(result.intent.kind).toBe("off-topic-to-other");
});
it("maps trigger based intents", async () => {
const result = await classifier.classify(undefined, "nickname-invalid");
expect(result.intent.kind).toBe("nickname-question");
expect(result.source).toBe("regex");
});
});
+233
View File
@@ -0,0 +1,233 @@
import { getClassifierMaxTokens } from "../../../config.js";
import { withClassifierSpan } from "@obs/spans";
import type { LlmClient } from "@llm/llm-client";
import {
detectLightweightIntent,
isRemainingStatusQuestion,
shouldSkipMessage,
} from "../message-filter.js";
import type { ClassifiedIntent, Intent } from "./onboarding-state.js";
interface ClassifierLlmShape {
intent?: string;
}
function intent(kind: Intent["kind"]): Intent {
return { kind };
}
function mapTriggerIntent(trigger: string): Intent | null {
switch (trigger) {
case "nickname-invalid":
return intent("nickname-question");
case "photo-failed":
return intent("photo-question");
case "progress-update":
case "timeout-warning":
return intent("status-question");
case "completed":
return intent("acknowledgement");
default:
return null;
}
}
function classifyByRegex(userMessage: string): ClassifiedIntent {
const trimmed = userMessage.trim();
const lower = trimmed.toLowerCase();
if (!trimmed) {
return { intent: intent("unknown"), confidence: 0, source: "regex" };
}
if (/^@\S+/u.test(trimmed)) {
return { intent: intent("off-topic-to-other"), confidence: 0.99, source: "regex" };
}
if (shouldSkipMessage(trimmed)) {
return { intent: intent("chitchat"), confidence: 0.95, source: "regex" };
}
const lightweightIntent = detectLightweightIntent(trimmed);
if (lightweightIntent === "greeting") {
return { intent: intent("greeting"), confidence: 0.99, source: "regex" };
}
if (lightweightIntent === "acknowledgement") {
return {
intent: intent("acknowledgement"),
confidence: 0.99,
source: "regex",
};
}
if (isRemainingStatusQuestion(trimmed)) {
return {
intent: intent("status-question"),
confidence: 0.96,
source: "regex",
};
}
if (/(어디|위치|어딨어|찾겠|찾을)/u.test(trimmed)) {
return { intent: intent("help-where"), confidence: 0.9, source: "regex" };
}
if (/(어떻게|방법|어케|어케해|어케 함|어케함)/u.test(trimmed)) {
return { intent: intent("help-how"), confidence: 0.9, source: "regex" };
}
if (/(디스코드|디코|discord)/u.test(lower)) {
return {
intent: intent("discord-question"),
confidence: 0.95,
source: "regex",
};
}
if (/(나이|연령|27세|나이\s*제한|몇\s*살|몇살)/u.test(trimmed)) {
return { intent: intent("age-question"), confidence: 0.93, source: "regex" };
}
if (/(닉네임|닉변|형식|이름)/u.test(trimmed)) {
return {
intent: intent("nickname-question"),
confidence: 0.9,
source: "regex",
};
}
if (/(하트|인증|사진|스크린샷|스샷|프로필)/u.test(trimmed)) {
return {
intent: intent("photo-question"),
confidence: 0.88,
source: "regex",
};
}
if (
/(가입|등록|절차|도움|도와|뭐해야|뭐 해야|해야 돼|해야해|무엇을 해야)/u.test(trimmed)
) {
return { intent: intent("help-how"), confidence: 0.72, source: "regex" };
}
return { intent: intent("unknown"), confidence: 0, source: "regex" };
}
function parseIntent(raw: unknown): Intent {
if (
raw === "greeting" ||
raw === "acknowledgement" ||
raw === "status-question" ||
raw === "help-how" ||
raw === "help-where" ||
raw === "nickname-question" ||
raw === "photo-question" ||
raw === "discord-question" ||
raw === "age-question" ||
raw === "chitchat" ||
raw === "off-topic-to-other"
) {
return { kind: raw };
}
return { kind: "unknown" };
}
async function classifyByLlm(
llmClient: LlmClient,
trigger: string,
userMessage: string,
): Promise<ClassifiedIntent> {
if (!llmClient.hasEndpoints()) {
return { intent: intent("unknown"), confidence: 0, source: "llm" };
}
const response = await llmClient.chatCompletion(
[
{
role: "system",
content:
'다음 유저 메시지의 intent를 JSON으로만 분류해. {"intent":"..."} 형식만 출력하고, intent는 greeting, acknowledgement, status-question, help-how, help-where, nickname-question, photo-question, discord-question, age-question, chitchat, off-topic-to-other, unknown 중 하나만 사용해.',
},
{
role: "user",
content: `trigger=${trigger}\nmessage=${userMessage}`,
},
],
{
jsonMode: true,
maxTokens: getClassifierMaxTokens(),
temperature: 0,
},
);
if (!response) {
return { intent: intent("unknown"), confidence: 0, source: "llm" };
}
try {
const parsed = JSON.parse(response.content) as ClassifierLlmShape;
return {
intent: parseIntent(parsed.intent),
confidence: parsed.intent ? 0.75 : 0,
source: "llm",
};
} catch {
return { intent: intent("unknown"), confidence: 0, source: "llm" };
}
}
export class OnboardingIntentClassifier {
constructor(private readonly llmClient: LlmClient) {}
async classify(
userMessage: string | undefined,
trigger: string,
): Promise<ClassifiedIntent> {
return withClassifierSpan(
{
"agent.trigger": trigger,
},
async (span) => {
const triggerIntent = mapTriggerIntent(trigger);
if (triggerIntent) {
span.setAttributes({
"agent.classifier.confidence": 1,
"agent.classifier.source": "regex",
"agent.intent": triggerIntent.kind,
});
return {
intent: triggerIntent,
confidence: 1,
source: "regex",
};
}
const regexResult = classifyByRegex(userMessage ?? "");
if (regexResult.confidence >= 0.75) {
span.setAttributes({
"agent.classifier.confidence": regexResult.confidence,
"agent.classifier.source": regexResult.source,
"agent.intent": regexResult.intent.kind,
});
return regexResult;
}
const llmResult = await classifyByLlm(
this.llmClient,
trigger,
userMessage ?? "",
);
const result =
llmResult.intent.kind === "unknown" ? regexResult : llmResult;
span.setAttributes({
"agent.classifier.confidence": result.confidence,
"agent.classifier.source": result.source,
"agent.intent": result.intent.kind,
});
return result;
},
);
}
}
@@ -0,0 +1,61 @@
import { describe, expect, it } from "vitest";
import { deriveState } from "./derive.js";
import type { Intent } from "./onboarding-state.js";
import type { OnboardingSession } from "../types.js";
function makeSession(
overrides?: Partial<OnboardingSession>,
): OnboardingSession {
return {
chatroomId: "room-1",
deadlineAt: new Date(Date.now() + 2 * 60 * 60 * 1000).toISOString(),
joinedAt: new Date().toISOString(),
lastEventAt: new Date().toISOString(),
nickname: "프리리/95/여/D",
nicknameVerified: false,
photoVerified: false,
status: "pending",
userId: "user-1",
...overrides,
};
}
function intent(kind: Intent["kind"]): Intent {
return { kind };
}
describe("deriveState", () => {
it("skips new-member trigger", () => {
const derived = deriveState(null, "new-member", intent("unknown"));
expect(derived.shouldRespond).toBe(false);
expect(derived.responseMode).toBe("skip");
expect(derived.tier).toBe(0);
});
it("skips chitchat intent", () => {
const derived = deriveState(makeSession(), "user-message", intent("chitchat"));
expect(derived.shouldRespond).toBe(false);
expect(derived.responseMode).toBe("skip");
});
it("promotes nickname-invalid to llm-with-tools tier1", () => {
const derived = deriveState(
makeSession(),
"nickname-invalid",
intent("nickname-question"),
);
expect(derived.responseMode).toBe("llm-with-tools");
expect(derived.tier).toBe(1);
});
it("allows short response for status questions", () => {
const derived = deriveState(
makeSession(),
"user-message",
intent("status-question"),
);
expect(derived.allowShortResponse).toBe(true);
expect(derived.suggestedMaxTokens).toBe(96);
});
});
+93
View File
@@ -0,0 +1,93 @@
import type { OnboardingSession } from "../types.js";
import { derivePhaseFromSession } from "./transitions.js";
import type { DerivedState, Intent } from "./onboarding-state.js";
function getSuggestedMaxTokens(
trigger: string,
intent: Intent,
): number {
if (intent.kind === "greeting" || intent.kind === "acknowledgement") {
return 96;
}
if (intent.kind === "status-question") {
return 96;
}
if (
trigger === "progress-update" ||
trigger === "timeout-warning" ||
trigger === "completed"
) {
return 256;
}
if (
intent.kind === "help-how" ||
intent.kind === "help-where" ||
intent.kind === "nickname-question" ||
intent.kind === "photo-question" ||
trigger === "nickname-invalid" ||
trigger === "photo-failed"
) {
return 384;
}
return 256;
}
function shouldAllowShortResponse(trigger: string, intent: Intent): boolean {
return (
trigger === "progress-update" ||
trigger === "timeout-warning" ||
trigger === "completed" ||
intent.kind === "greeting" ||
intent.kind === "acknowledgement" ||
intent.kind === "status-question"
);
}
export function deriveState(
session: OnboardingSession | null,
trigger: string,
intent: Intent,
): DerivedState {
const phase = derivePhaseFromSession(session, trigger);
if (
trigger === "new-member" ||
intent.kind === "chitchat" ||
intent.kind === "off-topic-to-other"
) {
return {
phase,
intent,
shouldRespond: false,
responseMode: "skip",
suggestedMaxTokens: 0,
allowShortResponse: true,
tier: 0,
};
}
let responseMode: DerivedState["responseMode"] = "llm";
let tier: DerivedState["tier"] = 0;
if (phase.kind === "nickname-rejected") {
responseMode = "llm-with-tools";
tier = 1;
} else if (phase.kind === "deadline-near") {
responseMode = "llm";
tier = 1;
}
return {
phase,
intent,
shouldRespond: true,
responseMode,
suggestedMaxTokens: getSuggestedMaxTokens(trigger, intent),
allowShortResponse: shouldAllowShortResponse(trigger, intent),
tier,
};
}
@@ -0,0 +1,16 @@
import type { Intent } from "./onboarding-state.js";
export const EXPECTED_KEYWORDS: Record<Intent["kind"], string[]> = {
acknowledgement: ["감사", "알겠", "확인"],
"age-question": ["27", "나이", "가입"],
chitchat: [],
"discord-question": ["디스코드", "디코", "discord"],
greeting: ["안녕", "반갑", "환영"],
"help-how": ["어떻게", "방법", "해"],
"help-where": ["어디", "위치", "찾"],
"nickname-question": ["닉네임", "닉변", "형식", "이름"],
"off-topic-to-other": [],
"photo-question": ["하트", "인증", "스크린샷", "프로필"],
"status-question": ["남았", "완료", "진행", "상태"],
unknown: [],
};
@@ -0,0 +1,44 @@
import type { NicknameIssue } from "../types.js";
export type RemainingStep = "nickname" | "photo";
export type OnboardingPhase =
| { kind: "fresh" }
| { kind: "nickname-pending"; current: string }
| { kind: "photo-pending" }
| { kind: "both-pending" }
| { kind: "nickname-rejected"; current: string; issues: NicknameIssue[] }
| { kind: "photo-rejected"; reason?: string | undefined }
| { kind: "deadline-near"; remaining: RemainingStep[] }
| { kind: "completed" }
| { kind: "timed-out" };
export type Intent =
| { kind: "greeting" }
| { kind: "acknowledgement" }
| { kind: "status-question" }
| { kind: "help-how" }
| { kind: "help-where" }
| { kind: "nickname-question" }
| { kind: "photo-question" }
| { kind: "discord-question" }
| { kind: "age-question" }
| { kind: "chitchat" }
| { kind: "off-topic-to-other" }
| { kind: "unknown" };
export interface DerivedState {
phase: OnboardingPhase;
intent: Intent;
shouldRespond: boolean;
responseMode: "skip" | "template" | "llm" | "llm-with-tools";
suggestedMaxTokens: number;
allowShortResponse: boolean;
tier: 0 | 1 | 2;
}
export interface ClassifiedIntent {
intent: Intent;
confidence: number;
source: "regex" | "llm";
}
@@ -0,0 +1,85 @@
import { getDeadlineNearThresholdMin } from "../../../config.js";
import { analyzeNicknameIssues } from "../onboarding-templates.js";
import type { OnboardingSession } from "../types.js";
import type { OnboardingPhase, RemainingStep } from "./onboarding-state.js";
function getRemainingSteps(
session: OnboardingSession | null,
): RemainingStep[] {
if (!session) {
return ["nickname", "photo"];
}
const remaining: RemainingStep[] = [];
if (!session.nicknameVerified) {
remaining.push("nickname");
}
if (!session.photoVerified) {
remaining.push("photo");
}
return remaining;
}
function isDeadlineNear(session: OnboardingSession | null): boolean {
if (!session?.deadlineAt) {
return false;
}
const deadlineAt = Date.parse(session.deadlineAt);
if (!Number.isFinite(deadlineAt)) {
return false;
}
return deadlineAt - Date.now() <= getDeadlineNearThresholdMin() * 60_000;
}
export function derivePhaseFromSession(
session: OnboardingSession | null,
trigger: string,
): OnboardingPhase {
if (!session) {
return { kind: "fresh" };
}
if (session.status === "timed_out") {
return { kind: "timed-out" };
}
if (session.status === "completed" || (session.nicknameVerified && session.photoVerified)) {
return { kind: "completed" };
}
if (trigger === "nickname-invalid") {
return {
kind: "nickname-rejected",
current: session.nickname,
issues: analyzeNicknameIssues(session.nickname),
};
}
if (trigger === "photo-failed") {
return { kind: "photo-rejected" };
}
const remaining = getRemainingSteps(session);
if (remaining.length > 0 && isDeadlineNear(session)) {
return { kind: "deadline-near", remaining };
}
if (!session.nicknameVerified && !session.photoVerified) {
return { kind: "both-pending" };
}
if (!session.nicknameVerified) {
return {
kind: "nickname-pending",
current: session.nickname,
};
}
if (!session.photoVerified) {
return { kind: "photo-pending" };
}
return { kind: "fresh" };
}