This commit is contained in:
dahyeon committed 2026-04-16 13:48:53 -07:00
commit 7fa293c9e8
59 files changed
+15526

No files matched your search

+185
View File
@@ -0,0 +1,185 @@
import type { Msg } from "nats";
import type { ConversationStore } from "@conv/conversation-store";
import type { NatsClient } from "@common/nats";
import { getRequestLogger, runWithContext } from "@obs/context";
import { getLogger } from "@obs/logger";
import { withSkillSpan, withSpan } from "@obs/spans";
import type { Skill } from "@skills/skill";
import type { AgentRequest, AgentResponse } from "./types.js";
import { getRequestSubject } from "../config.js";
function isValidRequest(data: unknown): data is AgentRequest {
if (typeof data !== "object" || data === null) return false;
const obj = data as Record<string, unknown>;
return (
typeof obj["requestId"] === "string" &&
typeof obj["skill"] === "string" &&
typeof obj["chatroomId"] === "string" &&
typeof obj["userId"] === "string" &&
typeof obj["nickname"] === "string" &&
typeof obj["trigger"] === "string"
);
}
export class Agent {
private readonly skills: Skill[] = [];
private readonly logger = getLogger();
constructor(
private readonly natsClient: NatsClient,
private readonly conversationStore: ConversationStore,
) {}
registerSkill(skill: Skill): void {
this.skills.push(skill);
this.logger.info({ skill: skill.name }, "✓ Skill registered");
}
async start(): Promise<void> {
const subject = getRequestSubject();
await this.natsClient.subscribeRaw(subject, async (msg: Msg) => {
await this.handleRequest(msg);
});
this.logger.info({ subject }, "✓ Agent listening on subject");
}
private async handleRequest(msg: Msg): Promise<void> {
let request: AgentRequest;
try {
const raw = JSON.parse(
new TextDecoder().decode(msg.data),
) as unknown;
if (!isValidRequest(raw)) {
this.logger.warn("[Agent] Invalid request received, skipping");
return;
}
request = raw;
} catch {
this.logger.warn("[Agent] Failed to parse request, skipping");
return;
}
await runWithContext(
{
chatroomId: request.chatroomId,
requestId: request.requestId,
skill: request.skill,
startedAt: new Date().toISOString(),
trigger: request.trigger,
userId: request.userId,
},
async () => {
const logger = getRequestLogger();
await withSpan(
"agent.handle",
{
"agent.chatroom_id": request.chatroomId,
"agent.request_id": request.requestId,
"agent.skill": request.skill,
"agent.trigger": request.trigger,
"agent.user_id": request.userId,
},
async (rootSpan) => {
logger.info(
{
nickname: request.nickname,
},
"[Agent] Request received",
);
const skill = this.skills.find((candidate) => candidate.canHandle(request));
if (!skill) {
logger.info("[Agent] No skill found for request");
const response: AgentResponse = {
requestId: request.requestId,
text: "",
confidence: 0,
source: "template",
};
rootSpan.setAttribute("agent.source", "template");
await this.natsClient.respond(msg, response);
return;
}
try {
const history = await this.conversationStore.getHistory(
request.chatroomId,
request.userId,
);
if (request.userMessage?.trim()) {
await this.conversationStore.appendMessage(
request.chatroomId,
request.userId,
{
role: "user",
content: request.userMessage,
timestamp: new Date().toISOString(),
},
);
}
const response = await withSkillSpan(
skill.name,
{
"agent.skill": skill.name,
"agent.trigger": request.trigger,
},
() => skill.handle(request, history),
);
if (response.text.trim()) {
await this.conversationStore.appendMessage(
request.chatroomId,
request.userId,
{
role: "assistant",
content: response.text,
timestamp: new Date().toISOString(),
},
);
}
await this.natsClient.respond(msg, response);
rootSpan.setAttribute(
"agent.source",
response.text.trim() ? response.source : "empty",
);
logger.info(
{
confidence: response.confidence,
length: response.text.length,
source: response.source,
},
"[Agent] Response sent",
);
} catch (error) {
logger.error(
{
err: error,
},
`[Agent] Skill ${skill.name} failed`,
);
const errorResponse: AgentResponse = {
requestId: request.requestId,
text: "",
confidence: 0,
source: "template",
metadata: {
error:
error instanceof Error ? error.message : String(error),
},
};
rootSpan.setAttribute("agent.source", "template");
await this.natsClient.respond(msg, errorResponse);
}
},
);
},
);
}
}
+6
View File
@@ -0,0 +1,6 @@
export type {
AgentRequest,
AgentResponse,
ConversationMessage,
} from "./types.js";
export { Agent } from "./agent.js";
+24
View File
@@ -0,0 +1,24 @@
export interface AgentRequest {
requestId: string;
skill: string;
chatroomId: string;
userId: string;
nickname: string;
trigger: string;
userMessage?: string | undefined;
context?: Record<string, unknown> | undefined;
}
export interface AgentResponse {
requestId: string;
text: string;
confidence: number;
source: "llm" | "template";
metadata?: Record<string, unknown> | undefined;
}
export interface ConversationMessage {
role: "user" | "assistant";
content: string;
timestamp: string;
}
+55
View File
@@ -0,0 +1,55 @@
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import * as dotenv from "dotenv";
import { getLogger } from "@obs/logger";
type NodeEnvMode = "dev" | "test" | "prod";
const VALID_MODES = new Set<NodeEnvMode>(["dev", "test", "prod"]);
const DEFAULT_MODE: NodeEnvMode = "dev";
let loaded = false;
const logger = getLogger();
function normalizeMode(raw: string | undefined): NodeEnvMode {
const input = (raw ?? "").trim().toLowerCase();
if (input === "development") return "dev";
if (input === "testing") return "test";
if (input === "production") return "prod";
if (VALID_MODES.has(input as NodeEnvMode)) return input as NodeEnvMode;
return DEFAULT_MODE;
}
function resolveEnvFile(mode: NodeEnvMode): string | null {
const moduleDir = path.dirname(fileURLToPath(import.meta.url));
const candidates = [
path.resolve(process.cwd(), "env-vars", `${mode}.env`),
path.resolve(moduleDir, "../../env-vars", `${mode}.env`),
];
for (const candidate of candidates) {
if (fs.existsSync(candidate)) return candidate;
}
return null;
}
export function loadEnvironmentFromNodeEnv(): void {
if (loaded) return;
loaded = true;
const mode = normalizeMode(process.env["NODE_ENV"]);
process.env["NODE_ENV"] = mode;
const envFile = resolveEnvFile(mode);
if (!envFile) {
logger.warn(`[Env] env-vars/${mode}.env not found. Skipping dotenv load.`);
return;
}
const result = dotenv.config({ path: envFile, override: false });
if (result.error) {
logger.warn(`[Env] Failed to load ${envFile}: ${result.error.message}`);
return;
}
}
+164
View File
@@ -0,0 +1,164 @@
import { createClient } from "redis";
import { getSecret } from "@common/secret-manager";
import { getLogger } from "@obs/logger";
type GarnetRedisClient = ReturnType<typeof createClient>;
function normalizeGarnetUrl(endpoint: string): string {
const trimmed = endpoint.trim();
if (!trimmed) {
throw new Error("GARNET_ENDPOINT cannot be empty");
}
if (/^redis(s)?:\/\//iu.test(trimmed)) {
return trimmed;
}
return `redis://${trimmed}`;
}
export class GarnetClient {
private client: GarnetRedisClient | null = null;
private readonly logger = getLogger();
private getClient(): GarnetRedisClient {
if (!this.client) {
throw new Error("Garnet client not connected");
}
return this.client;
}
async connect(): Promise<void> {
const endpoint = getSecret("GARNET_ENDPOINT");
const username = getSecret("GARNET_USERID");
const password = getSecret("GARNET_PASSWORD");
if (!endpoint || !username || !password) {
throw new Error("Missing Garnet credentials in secrets");
}
const client = createClient({
password,
url: normalizeGarnetUrl(endpoint),
username,
});
client.on("error", (error) => {
this.logger.error({ err: error }, "[Garnet] Client error");
});
await client.connect();
this.client = client;
this.logger.info("✓ Garnet connected");
}
async getJson<T>(key: string): Promise<T | null> {
const rawValue = await this.getClient().get(key);
if (!rawValue) {
return null;
}
return JSON.parse(rawValue) as T;
}
async setJson(
key: string,
value: unknown,
ttlSeconds?: number,
): Promise<void> {
const serialized = JSON.stringify(value);
const client = this.getClient();
if (ttlSeconds && ttlSeconds > 0) {
await client.set(key, serialized, { EX: ttlSeconds });
return;
}
await client.set(key, serialized);
}
async getString(key: string): Promise<string | null> {
return this.getClient().get(key);
}
async setString(
key: string,
value: string,
ttlSeconds?: number,
): Promise<void> {
const client = this.getClient();
if (ttlSeconds && ttlSeconds > 0) {
await client.set(key, value, { EX: ttlSeconds });
return;
}
await client.set(key, value);
}
async delete(key: string): Promise<number> {
return this.getClient().del(key);
}
async getHash(key: string): Promise<Record<string, string>> {
return this.getClient().hGetAll(key);
}
async setHash(
key: string,
fields: Record<string, string>,
): Promise<void> {
await this.getClient().hSet(key, fields);
}
async appendStream(
key: string,
fields: Record<string, string>,
options?: { maxLen?: number | undefined },
): Promise<string> {
const trimOptions =
options?.maxLen && options.maxLen > 0
? {
TRIM: {
strategy: "MAXLEN" as const,
strategyModifier: "~" as const,
threshold: options.maxLen,
},
}
: undefined;
return this.getClient().xAdd(key, "*", fields, trimOptions);
}
async scanKeys(pattern: string): Promise<string[]> {
const keys: string[] = [];
for await (const batch of this.getClient().scanIterator({
COUNT: 100,
MATCH: pattern,
})) {
for (const key of batch) {
keys.push(String(key));
}
}
return keys;
}
async close(): Promise<void> {
if (!this.client) {
return;
}
const client = this.client;
this.client = null;
try {
await client.quit();
} catch {
client.destroy();
}
}
}
+12
View File
@@ -0,0 +1,12 @@
export const KNOWN_SECRET_KEYS = [
"NATS_ENDPOINT",
"NATS_PASS",
"NATS_USER",
"GARNET_ENDPOINT",
"GARNET_USERID",
"GARNET_PASSWORD",
"MONGODB_CONNECTION_STRING",
"MONGODB_PROJECT_ID",
] as const;
export type KnownSecretKey = (typeof KNOWN_SECRET_KEYS)[number];
+43
View File
@@ -0,0 +1,43 @@
import mongoose from "mongoose";
import { getLogger } from "@obs/logger";
let connection: mongoose.Connection | null = null;
const logger = getLogger();
export async function initMongoDB(
connectionString: string,
): Promise<mongoose.Connection> {
if (connection !== null) {
return connection;
}
if (!connectionString) {
throw new Error(
"MongoDB connection string is empty. Set MONGODB_CONNECTION_STRING.",
);
}
connection = await mongoose
.createConnection(connectionString, { dbName: "dakao" })
.asPromise();
logger.info("✓ MongoDB connection initialized");
return connection;
}
export function getMongoConnection(): mongoose.Connection {
if (connection === null) {
throw new Error(
"MongoDB connection is not initialized. Call initMongoDB() in main.ts first.",
);
}
return connection;
}
export async function closeMongoDB(): Promise<void> {
if (connection === null) {
return;
}
await connection.close();
connection = null;
}
+137
View File
@@ -0,0 +1,137 @@
import {
type Msg,
type NatsConnection,
StringCodec,
connect,
type Subscription,
} from "nats";
import { getSecret } from "@common/secret-manager";
import { getLogger } from "@obs/logger";
export interface NatsMessageContext<T = unknown> {
data: T;
raw: Msg;
reply: string | undefined;
subject: string;
subscriptionSubject: string;
}
export class NatsClient {
private client: NatsConnection | null = null;
private readonly stringCodec = StringCodec();
private readonly logger = getLogger();
private getConnection(): NatsConnection {
if (!this.client) {
throw new Error("NATS client not connected");
}
return this.client;
}
private decodeMessage<T>(msg: Msg): T {
return JSON.parse(this.stringCodec.decode(msg.data)) as T;
}
async connect(): Promise<void> {
const endpoint = getSecret("NATS_ENDPOINT");
const user = getSecret("NATS_USER");
const password = getSecret("NATS_PASS");
if (!endpoint || !user || !password) {
throw new Error("Missing NATS credentials in secrets");
}
this.client = await connect({
name: process.env["SERVICE_NAME"] || "lolympus-agent",
servers: [endpoint],
tls: {},
maxReconnectAttempts: -1,
reconnectTimeWait: 500,
reconnect: true,
pingInterval: 20000,
timeout: 5000,
user: user,
pass: password,
});
this.logger.info("✓ NATS connected");
}
async subscribe<T = unknown>(
subject: string,
handler: (
data: T,
context: NatsMessageContext<T>,
) => void | Promise<void>,
): Promise<Subscription> {
return this.subscribeRaw(subject, async (msg) => {
const data = this.decodeMessage<T>(msg);
await handler(data, {
data,
raw: msg,
reply: msg.reply || undefined,
subject: msg.subject,
subscriptionSubject: subject,
});
});
}
subscribeRaw(
subject: string,
handler: (msg: Msg) => void | Promise<void>,
): Promise<Subscription> {
const subscription = this.getConnection().subscribe(subject);
void (async () => {
for await (const msg of subscription) {
try {
await handler(msg);
} catch (error) {
this.logger.error(
{ err: error, subject: msg.subject },
"[NATS] Error processing message",
);
}
}
})();
this.logger.info({ subject }, "✓ Subscribed to subject");
return Promise.resolve(subscription);
}
async publish<T = unknown>(subject: string, data: T): Promise<void> {
const client = this.getConnection();
client.publish(subject, this.stringCodec.encode(JSON.stringify(data)));
await client.flush();
}
respond(msg: Msg, data: unknown): Promise<void> {
if (!msg.reply) {
this.logger.warn(
{ subject: msg.subject },
"[NATS] Cannot respond: no reply subject",
);
return Promise.resolve();
}
msg.respond(this.stringCodec.encode(JSON.stringify(data)));
return Promise.resolve();
}
async close(): Promise<void> {
if (!this.client) return;
try {
const closed = this.client.closed();
await this.client.drain();
const err = await closed;
if (err) {
this.logger.error({ err }, "[NATS] Closed with error");
}
} catch {
try {
await this.client.close();
} catch {}
}
}
}
+84
View File
@@ -0,0 +1,84 @@
import { InfisicalSDK } from "@infisical/sdk";
import { KNOWN_SECRET_KEYS, type KnownSecretKey } from "./known-secret-keys.js";
export type SecretMap = Partial<Record<KnownSecretKey, string>>;
export type RawSecretMap = Record<string, string>;
const INFISICAL_SITE_URL = "https://secret-manager.dahyeon.us/";
const KNOWN_SECRET_KEY_SET = new Set<string>(KNOWN_SECRET_KEYS);
const infisicalClient = new InfisicalSDK({ siteUrl: INFISICAL_SITE_URL });
export let secrets: SecretMap | null = null;
export let rawSecrets: RawSecretMap | null = null;
function isKnownSecretKey(value: string): value is KnownSecretKey {
return KNOWN_SECRET_KEY_SET.has(value);
}
function getInfisicalCredentials(): {
clientSecret: string;
clientId: string;
projectId: string;
} | null {
const clientSecret = process.env["INFISICAL_CLIENT_SECRET"] ?? "";
const clientId = process.env["INFISICAL_CLIENT_ID"] ?? "";
const projectId = process.env["INFISICAL_PROJECT_ID"] ?? "";
if (!clientSecret || !clientId || !projectId) {
return null;
}
return { clientSecret, clientId, projectId };
}
function getInfisicalEnvironment(): "dev" | "staging" | "prod" {
if (process.env["NODE_ENV"] === "prod") return "prod";
if (process.env["NODE_ENV"] === "test") return "staging";
return "dev";
}
export function getSecret(key: KnownSecretKey): string | undefined {
return secrets?.[key] ?? process.env[key];
}
export function getRawSecret(key: string): string | undefined {
return rawSecrets?.[key] ?? process.env[key];
}
const fetchSecrets = async (): Promise<{
known: SecretMap;
raw: RawSecretMap;
}> => {
const credentials = getInfisicalCredentials();
if (!credentials) {
return { known: {}, raw: {} };
}
try {
await infisicalClient.auth().universalAuth.login({
clientId: credentials.clientId,
clientSecret: credentials.clientSecret,
});
const res = await infisicalClient.secrets().listSecrets({
environment: getInfisicalEnvironment(),
projectId: credentials.projectId,
});
const known: SecretMap = {};
const raw: RawSecretMap = {};
for (const s of res.secrets) {
if (!s.secretKey) continue;
raw[s.secretKey] = s.secretValue ?? "";
if (isKnownSecretKey(s.secretKey)) {
known[s.secretKey] = s.secretValue ?? "";
}
}
return { known, raw };
} catch {
return { known: {}, raw: {} };
}
};
const loaded = await fetchSecrets();
secrets = loaded.known;
rawSecrets = loaded.raw;
+153
View File
@@ -0,0 +1,153 @@
type LogLevel =
| "fatal"
| "error"
| "warn"
| "info"
| "debug"
| "trace"
| "silent";
function getPositiveNumber(
envKey: string,
fallback: number,
): number {
const raw = process.env[envKey]?.trim();
if (!raw) return fallback;
const parsed = Number(raw);
return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
}
function getRatioNumber(
envKey: string,
fallback: number,
): number {
const raw = process.env[envKey]?.trim();
if (!raw) return fallback;
const parsed = Number(raw);
return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1
? parsed
: fallback;
}
export function getNodeEnv(): "dev" | "test" | "prod" {
const value = process.env["NODE_ENV"]?.trim();
return value === "test" || value === "prod" ? value : "dev";
}
export function getServiceName(): string {
return process.env["SERVICE_NAME"]?.trim() || "lolympus-agent";
}
export function getLogLevel(): LogLevel {
const raw = process.env["LOG_LEVEL"]?.trim().toLowerCase() as
| LogLevel
| undefined;
if (
raw === "fatal" ||
raw === "error" ||
raw === "warn" ||
raw === "info" ||
raw === "debug" ||
raw === "trace" ||
raw === "silent"
) {
return raw;
}
const nodeEnv = getNodeEnv();
if (nodeEnv === "prod") return "warn";
if (nodeEnv === "test") return "debug";
return "trace";
}
export function getOtelSamplingRatio(): number {
const fallback = getNodeEnv() === "prod" ? 0.1 : 1.0;
return getRatioNumber("OTEL_SAMPLING_RATIO", fallback);
}
export function getOtelExporter(): "stdout" {
return "stdout";
}
export function getRequestSubject(): string {
return (
process.env["AGENT_REQUEST_SUBJECT"]?.trim() || "lolympus-agent.request"
);
}
export function getOnboardingSessionKeyPrefix(): string {
return process.env["ONBOARDING_SESSION_KEY_PREFIX"]?.trim() || "lolympus";
}
export function getConversationTtlSeconds(): number {
return getPositiveNumber("CONVERSATION_TTL_SECONDS", 12 * 60 * 60);
}
export function getBlackboardTtlSeconds(): number {
return getPositiveNumber("BLACKBOARD_TTL_SEC", 12 * 60 * 60);
}
export function getConversationSummaryTtlSeconds(): number {
return getPositiveNumber("CONVERSATION_SUMMARY_TTL_SEC", 24 * 60 * 60);
}
export function getBackgroundStreamMaxLen(): number {
return getPositiveNumber("BACKGROUND_STREAM_MAXLEN", 5_000);
}
export function getMaxConversationMessages(): number {
return getPositiveNumber("MAX_CONVERSATION_MESSAGES", 20);
}
export function getLlmRequestTimeoutMs(): number {
return getPositiveNumber("LLM_REQUEST_TIMEOUT_MS", 30_000);
}
export function getLlmHealthTimeoutMs(): number {
return getPositiveNumber("LLM_HEALTH_TIMEOUT_MS", 5_000);
}
export function getLlmHealthCacheTtlMs(): number {
return getPositiveNumber("LLM_HEALTH_CACHE_TTL_MS", 30_000);
}
export function getLlmCircuitFailureThreshold(): number {
return getPositiveNumber("LLM_CIRCUIT_FAILURE_THRESHOLD", 3);
}
export function getLlmCircuitCooldownMs(): number {
return getPositiveNumber("LLM_CIRCUIT_COOLDOWN_MS", 60_000);
}
export function getClassifierMaxTokens(): number {
return getPositiveNumber("CLASSIFIER_MAX_TOKENS", 16);
}
export function getDeadlineNearThresholdMin(): number {
return getPositiveNumber("DEADLINE_NEAR_THRESHOLD_MIN", 30);
}
export function getLlmMaxTokens(): number {
return getPositiveNumber("LLM_MAX_TOKENS", 768);
}
export function getLlmTemperature(): number {
const raw = process.env["LLM_TEMPERATURE"]?.trim();
if (raw) {
const n = Number(raw);
if (Number.isFinite(n) && n >= 0 && n <= 2) return n;
}
return 0.55;
}
export function getMaxResponseLength(): number {
return getPositiveNumber("MAX_RESPONSE_LENGTH", 600);
}
export function getMongoDbProjectId(): string | undefined {
return process.env["MONGODB_PROJECT_ID"]?.trim() || undefined;
}
export function getRoomContextLimit(): number {
return getPositiveNumber("ROOM_CONTEXT_LIMIT", 8);
}
+93
View File
@@ -0,0 +1,93 @@
import type { ConversationMessage } from "@agent/types";
import type { GarnetClient } from "@common/garnet";
import {
getBackgroundStreamMaxLen,
getConversationTtlSeconds,
getConversationSummaryTtlSeconds,
getMaxConversationMessages,
} from "../config.js";
const BACKGROUND_STREAM_KEY = "lolympus-agent:background";
export function getConversationKey(chatroomId: string, userId: string): string {
return `lolympus-agent:conv:${chatroomId}:${userId}`;
}
export function getConversationSummaryKey(
chatroomId: string,
userId: string,
): string {
return `lolympus-agent:summary:${chatroomId}:${userId}`;
}
export class ConversationStore {
constructor(private readonly garnetClient: GarnetClient) {}
async getHistory(
chatroomId: string,
userId: string,
): Promise<ConversationMessage[]> {
const key = getConversationKey(chatroomId, userId);
const messages =
await this.garnetClient.getJson<ConversationMessage[]>(key);
return messages ?? [];
}
async appendMessage(
chatroomId: string,
userId: string,
message: ConversationMessage,
): Promise<void> {
const key = getConversationKey(chatroomId, userId);
const messages = await this.getHistory(chatroomId, userId);
messages.push(message);
const maxMessages = getMaxConversationMessages();
const trimmed =
messages.length > maxMessages
? messages.slice(messages.length - maxMessages)
: messages;
await this.garnetClient.setJson(key, trimmed, getConversationTtlSeconds());
if (trimmed.length > 5) {
await this.garnetClient.appendStream(
BACKGROUND_STREAM_KEY,
{
type: "summarize",
chatroomId,
userId,
},
{
maxLen: getBackgroundStreamMaxLen(),
},
);
}
}
async getSummary(chatroomId: string, userId: string): Promise<string | null> {
const key = getConversationSummaryKey(chatroomId, userId);
return this.garnetClient.getString(key);
}
async setSummary(
chatroomId: string,
userId: string,
summary: string,
): Promise<void> {
const key = getConversationSummaryKey(chatroomId, userId);
await this.garnetClient.setString(
key,
summary,
getConversationSummaryTtlSeconds(),
);
}
async clear(chatroomId: string, userId: string): Promise<void> {
const key = getConversationKey(chatroomId, userId);
const summaryKey = getConversationSummaryKey(chatroomId, userId);
await this.garnetClient.delete(key);
await this.garnetClient.delete(summaryKey);
}
}
+2
View File
@@ -0,0 +1,2 @@
export { ConversationStore } from "./conversation-store.js";
export { summarizeConversation } from "./summarizer.js";
+42
View File
@@ -0,0 +1,42 @@
import type { ConversationMessage } from "@agent/types";
import type { LlmClient } from "@llm/llm-client";
function formatHistory(history: ConversationMessage[]): string {
return history.map((message) => `${message.role}: ${message.content}`).join("\n");
}
export async function summarizeConversation(
llmClient: LlmClient,
history: ConversationMessage[],
existingSummary?: string | undefined,
): Promise<string> {
if (!llmClient.hasEndpoints() || history.length === 0) {
return existingSummary ?? "";
}
const response = await llmClient.chatCompletion(
[
{
role: "system",
content:
"다음 대화를 3문장 이내의 한국어 메모로 요약해. 온보딩 진행상태, 아직 남은 질문, 톤 관련 단서만 남겨.",
},
{
role: "user",
content: [
existingSummary ? `[기존 요약]\n${existingSummary}` : "",
"[최근 대화]",
formatHistory(history),
]
.filter(Boolean)
.join("\n\n"),
},
],
{
maxTokens: 256,
temperature: 0.2,
},
);
return response?.content.trim() ?? existingSummary ?? "";
}
+53
View File
@@ -0,0 +1,53 @@
import { createHash } from "node:crypto";
const EVAL_ANON_SALT = "lolympus-agent-v1" as const;
function shortHash(value: string): string {
return createHash("sha256")
.update(`${EVAL_ANON_SALT}:${value}`)
.digest("hex")
.slice(0, 8);
}
export function anonymizeIdentifier(
prefix: string,
value: string | undefined,
): string | undefined {
if (!value?.trim()) {
return undefined;
}
return `${prefix}_${shortHash(value)}`;
}
export function anonymizeNickname(value: string | undefined): string | undefined {
if (!value?.trim()) {
return undefined;
}
return `<nick:${shortHash(value)}>`;
}
export function anonymizeText(value: string): string {
return value
.replace(/01[016789][- ]?\d{3,4}[- ]?\d{4}/gu, "[REDACTED:phone]")
.replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/giu, "[REDACTED:email]")
.replace(/\b(?:\d[ -]?){13,19}\b/gu, "[REDACTED:card]")
.replace(/https?:\/\/open\.kakao\.com\/o\/[^\s)]+/giu, "[REDACTED:kakao-link]")
.replace(/https?:\/\/discord\.gg\/[^\s)]+/giu, "[REDACTED:discord-link]")
.replace(/discord\.gg\/[^\s)]+/giu, "[REDACTED:discord-link]");
}
export function anonymizeRelativeTimestamp(
value: Date | string,
baseTimestamp: Date,
): string {
const timestamp =
value instanceof Date ? value.getTime() : Date.parse(value);
if (!Number.isFinite(timestamp)) {
return "+0s";
}
const seconds = Math.round((timestamp - baseTimestamp.getTime()) / 1000);
return `${seconds >= 0 ? "+" : ""}${seconds}s`;
}
+132
View File
@@ -0,0 +1,132 @@
import { mkdir, writeFile } from "node:fs/promises";
import { dirname, resolve } from "node:path";
import { initMongoDB, closeMongoDB, getMongoConnection } from "@common/mongodb";
import { getSecret } from "@common/secret-manager";
import { getLogger } from "@obs/logger";
import {
anonymizeIdentifier,
anonymizeNickname,
anonymizeRelativeTimestamp,
anonymizeText,
} from "./anonymize.js";
interface CaptureOptions {
limit?: number | undefined;
outputPath?: string | undefined;
}
function asRecord(value: unknown): Record<string, unknown> {
return typeof value === "object" && value !== null
? (value as Record<string, unknown>)
: {};
}
function extractMessageText(doc: Record<string, unknown>): string | null {
const data = asRecord(doc["data"]);
const body = asRecord(data["body"]);
const chatLog = asRecord(body["chatLog"]);
const text =
(typeof chatLog["message"] === "string" ? chatLog["message"] : null) ??
(typeof body["message"] === "string" ? body["message"] : null);
return text?.trim() || null;
}
function extractNickname(doc: Record<string, unknown>): string | undefined {
const data = asRecord(doc["data"]);
const body = asRecord(data["body"]);
return typeof body["authorNickname"] === "string"
? body["authorNickname"]
: undefined;
}
export async function captureGoldenSetScaffold(
options?: CaptureOptions,
): Promise<string> {
const logger = getLogger();
const connectionString =
getSecret("MONGODB_CONNECTION_STRING") ??
process.env["MONGODB_CONNECTION_STRING"];
if (!connectionString) {
throw new Error("Missing MONGODB_CONNECTION_STRING for eval capture");
}
await initMongoDB(connectionString);
try {
const connection = getMongoConnection();
const collection = connection.collection("events");
const limit = options?.limit ?? 30;
const docs = (await collection
.find({ category: "message.received" })
.sort({ timestamp: -1 })
.limit(limit)
.toArray()) as Array<Record<string, unknown>>;
const baseTimestamp = (() => {
const lastDoc = docs[docs.length - 1];
const raw = lastDoc?.["timestamp"];
const parsed =
raw instanceof Date ? raw : new Date(typeof raw === "string" ? raw : Date.now());
return parsed;
})();
const lines = docs.map((doc) => {
const rawTimestamp = doc["timestamp"];
const messageText = extractMessageText(doc) ?? "";
const chatroomId = anonymizeIdentifier(
"room",
typeof doc["chatroomId"] === "string" ? doc["chatroomId"] : undefined,
);
const userId = anonymizeIdentifier(
"user",
typeof doc["senderId"] === "string" ? doc["senderId"] : undefined,
);
const nickname = anonymizeNickname(extractNickname(doc));
return JSON.stringify({
input: {
request: {
requestId: `capture_${Math.random().toString(36).slice(2, 10)}`,
skill: "onboarding",
chatroomId: chatroomId,
userId: userId,
nickname,
trigger: "user-message",
userMessage: anonymizeText(messageText),
capturedAt: anonymizeRelativeTimestamp(
rawTimestamp instanceof Date
? rawTimestamp
: typeof rawTimestamp === "string"
? rawTimestamp
: baseTimestamp,
baseTimestamp,
),
},
roomContext: [],
session: null,
},
expected: {
intent: "",
mustIncludeAny: [],
mustNotInclude: [],
responseMode: "",
},
});
});
const outputPath = resolve(
process.cwd(),
options?.outputPath ?? "src/eval/golden/onboarding.capture.jsonl",
);
await mkdir(dirname(outputPath), { recursive: true });
await writeFile(outputPath, `${lines.join("\n")}\n`, "utf8");
logger.info({ count: lines.length, outputPath }, "[Eval] Capture scaffold written");
return outputPath;
} finally {
await closeMongoDB();
}
}
+38
View File
@@ -0,0 +1,38 @@
function printPhaseNotice(command: string): void {
console.info(
`[eval] "${command}" is not implemented yet. Phase 5 will add the full eval flow.`,
);
}
function parsePositiveInteger(value: string | undefined): number | undefined {
if (!value?.trim()) {
return undefined;
}
const parsed = Number(value);
return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
}
async function main(): Promise<void> {
const { loadEnvironmentFromNodeEnv } = await import("@common/env-loader");
loadEnvironmentFromNodeEnv();
const { getLogger, initLogger } = await import("@obs/logger");
initLogger();
const { captureGoldenSetScaffold } = await import("./capture.js");
const [command = "run", arg1, arg2] = process.argv.slice(2);
if (command === "capture") {
const outputPath = await captureGoldenSetScaffold({
limit: parsePositiveInteger(arg1),
outputPath: arg2,
});
getLogger().info({ outputPath }, '[eval] "capture" completed');
return;
}
printPhaseNotice(command);
}
void main();
+187
View File
@@ -0,0 +1,187 @@
import { createHash } from 'node:crypto';
import type { GarnetClient } from '@common/garnet';
import { getLogger } from '@obs/logger';
import {
getLlmCircuitCooldownMs,
getLlmCircuitFailureThreshold,
getLlmHealthCacheTtlMs,
} from '../config.js';
type CircuitStatus = 'healthy' | 'open' | 'unhealthy';
interface CircuitRecord {
failureCount: number;
lastCheckedAt: number;
openedAt?: number;
state: CircuitStatus;
}
const MAX_LOCAL_CACHE_ENTRIES = 128;
function now(): number {
return Date.now();
}
export class LlmCircuitBreaker {
private readonly localCache = new Map<string, CircuitRecord>();
private readonly logger = getLogger();
constructor(private readonly garnetClient?: GarnetClient) {}
async canUse(
endpoint: string,
healthCheck: () => Promise<boolean>,
): Promise<boolean> {
const record = await this.getRecord(endpoint);
const currentTime = now();
if (
record?.state === 'open' &&
record.openedAt !== undefined &&
currentTime - record.openedAt < getLlmCircuitCooldownMs()
) {
return false;
}
if (
record !== undefined &&
currentTime - record.lastCheckedAt < getLlmHealthCacheTtlMs()
) {
return record.state === 'healthy';
}
const healthy = await healthCheck();
if (healthy) {
await this.recordSuccess(endpoint);
return true;
}
await this.recordFailure(endpoint);
return false;
}
async recordSuccess(endpoint: string): Promise<void> {
await this.setRecord(endpoint, {
failureCount: 0,
lastCheckedAt: now(),
state: 'healthy',
});
}
async recordFailure(endpoint: string): Promise<void> {
const record = await this.getRecord(endpoint);
const failureCount = (record?.failureCount ?? 0) + 1;
const shouldOpen = failureCount >= getLlmCircuitFailureThreshold();
const nextRecord: CircuitRecord = {
failureCount,
lastCheckedAt: now(),
state: shouldOpen ? 'open' : 'unhealthy',
};
if (shouldOpen) {
nextRecord.openedAt = now();
}
await this.setRecord(endpoint, nextRecord);
}
private async getRecord(endpoint: string): Promise<CircuitRecord | undefined> {
const key = this.getKey(endpoint);
const local = this.localCache.get(key);
if (local !== undefined) {
return local;
}
if (!this.garnetClient) {
return undefined;
}
const stored = await this.garnetClient.getHash(key);
if (Object.keys(stored).length === 0) {
return undefined;
}
const record = this.deserializeRecord(stored);
if (!record) {
return undefined;
}
this.setLocalRecord(key, record);
return record;
}
private async setRecord(
endpoint: string,
record: CircuitRecord,
): Promise<void> {
const key = this.getKey(endpoint);
this.setLocalRecord(key, record);
if (!this.garnetClient) {
return;
}
await this.garnetClient.setHash(key, {
failureCount: String(record.failureCount),
lastCheckedAt: String(record.lastCheckedAt),
openedAt: record.openedAt !== undefined ? String(record.openedAt) : '',
state: record.state,
});
this.logger.debug(
{
endpointHash: key,
failureCount: record.failureCount,
state: record.state,
},
'[LLM] Circuit state updated',
);
}
private setLocalRecord(
key: string,
record: CircuitRecord,
): void {
if (this.localCache.size >= MAX_LOCAL_CACHE_ENTRIES) {
const oldestKey = this.localCache.keys().next().value;
if (oldestKey) {
this.localCache.delete(oldestKey);
}
}
this.localCache.set(key, record);
}
private deserializeRecord(
raw: Record<string, string>,
): CircuitRecord | undefined {
const lastCheckedAt = Number(raw['lastCheckedAt']);
const failureCount = Number(raw['failureCount']);
const state = raw['state'];
const openedAtRaw = raw['openedAt'];
if (
!Number.isFinite(lastCheckedAt) ||
!Number.isFinite(failureCount) ||
(state !== 'healthy' && state !== 'open' && state !== 'unhealthy')
) {
return undefined;
}
const record: CircuitRecord = {
failureCount,
lastCheckedAt,
state,
};
if (openedAtRaw && Number.isFinite(Number(openedAtRaw))) {
record.openedAt = Number(openedAtRaw);
}
return record;
}
private getKey(endpoint: string): string {
const endpointHash = createHash('sha1').update(endpoint).digest('hex');
return `lolympus-agent:circuit:${endpointHash}`;
}
}
+8
View File
@@ -0,0 +1,8 @@
export type {
ChatCompletionRequest,
ChatCompletionResponse,
ChatMessage,
LlmClientOptions,
LlmEndpointConfig,
} from "./types.js";
export { LlmClient } from "./llm-client.js";
+250
View File
@@ -0,0 +1,250 @@
import type {
ChatCompletionRequest,
ChatCompletionResponse,
ChatMessage,
LlmClientOptions,
LlmEndpointConfig,
} from "./types.js";
import { getRequestLogger } from "@obs/context";
import { withLlmSpan } from "@obs/spans";
import {
getLlmHealthTimeoutMs,
getLlmMaxTokens,
getLlmRequestTimeoutMs,
getLlmTemperature,
} from "../config.js";
import { LlmCircuitBreaker } from "./circuit.js";
const DEFAULT_MODEL = "Qwen3.5-4B";
function buildCliProxyHealthUrl(endpoint: string): string {
try {
const url = new URL(endpoint);
url.pathname = "/";
url.search = "";
url.hash = "";
return url.toString();
} catch {
const normalized = endpoint.replace(/\/v1\/chat\/completions\/?$/u, "");
return `${normalized.replace(/\/+$/u, "")}/`;
}
}
function normalizeEndpointConfig(
endpoint: string | { url: string; provider?: "default" | "cliproxy" },
): LlmEndpointConfig {
const raw =
typeof endpoint === "string"
? { provider: "default" as const, url: endpoint }
: { provider: endpoint.provider ?? "default", url: endpoint.url };
return {
completionUrl: buildCompletionUrl(raw.url),
healthUrl:
raw.provider === "cliproxy"
? buildCliProxyHealthUrl(raw.url)
: buildHealthUrl(raw.url),
provider: raw.provider,
};
}
function buildCompletionUrl(endpoint: string): string {
try {
const url = new URL(endpoint);
if (!url.pathname || url.pathname === "/") {
url.pathname = "/v1/chat/completions";
}
url.search = "";
url.hash = "";
return url.toString();
} catch {
if (endpoint.includes("/v1/chat/completions")) {
return endpoint;
}
return `${endpoint.replace(/\/+$/u, "")}/v1/chat/completions`;
}
}
function buildHealthUrl(endpoint: string): string {
try {
const url = new URL(endpoint);
url.pathname = "/health";
url.search = "";
url.hash = "";
return url.toString();
} catch {
if (endpoint.includes("/v1/chat/completions")) {
return `${endpoint.split("/v1/chat/completions")[0]}/health`;
}
return `${endpoint.replace(/\/+$/u, "")}/health`;
}
}
export class LlmClient {
private readonly circuit: LlmCircuitBreaker;
private readonly endpoints: LlmEndpointConfig[];
private readonly apiKey: string | undefined;
private readonly model: string;
constructor(options: LlmClientOptions) {
this.circuit = new LlmCircuitBreaker(options.garnetClient);
this.endpoints = options.endpoints.map(normalizeEndpointConfig);
this.apiKey = options.apiKey;
this.model = options.model ?? DEFAULT_MODEL;
}
private getHeaders(includeJson = false): Record<string, string> {
const headers: Record<string, string> = {};
if (includeJson) {
headers["Content-Type"] = "application/json";
}
if (this.apiKey) {
headers["Authorization"] = `Bearer ${this.apiKey}`;
}
return headers;
}
private async checkHealth(endpoint: LlmEndpointConfig): Promise<boolean> {
try {
const response = await fetch(endpoint.healthUrl, {
headers: this.getHeaders(),
method: "GET",
signal: AbortSignal.timeout(getLlmHealthTimeoutMs()),
});
if (endpoint.provider === "cliproxy") {
return response.status === 200;
}
return response.ok;
} catch {
return false;
}
}
async chatCompletion(
messages: ChatMessage[],
options?: {
jsonMode?: boolean | undefined;
maxTokens?: number | undefined;
temperature?: number | undefined;
},
): Promise<{ content: string; endpoint: string } | null> {
const logger = getRequestLogger();
if (this.endpoints.length === 0) {
logger.warn("[LLM] No endpoints configured");
return null;
}
const request: ChatCompletionRequest = {
model: this.model,
messages,
max_tokens: options?.maxTokens ?? getLlmMaxTokens(),
temperature: options?.temperature ?? getLlmTemperature(),
};
if (options?.jsonMode) {
request.response_format = { type: "json_object" };
}
for (const endpoint of this.endpoints) {
const healthy = await this.circuit.canUse(
endpoint.completionUrl,
() => this.checkHealth(endpoint),
);
if (!healthy) {
logger.warn(
{
endpoint: endpoint.completionUrl,
provider: endpoint.provider ?? 'default',
},
"[LLM] Endpoint unavailable via circuit breaker",
);
continue;
}
try {
const llmResult = await withLlmSpan(
{
"gen_ai.request.model": request.model,
"gen_ai.system": endpoint.provider ?? 'default',
},
async (span) => {
const response = await fetch(endpoint.completionUrl, {
body: JSON.stringify(request),
headers: this.getHeaders(true),
method: "POST",
signal: AbortSignal.timeout(getLlmRequestTimeoutMs()),
});
if (!response.ok) {
const body = (await response.text()).slice(0, 500);
logger.warn(
{
endpoint: endpoint.completionUrl,
provider: endpoint.provider ?? 'default',
status: response.status,
body,
},
"[LLM] Request failed",
);
return null;
}
const payload = (await response.json()) as ChatCompletionResponse;
const content = payload.choices?.[0]?.message?.content;
span.setAttributes({
"gen_ai.response.finish_reasons": payload.choices
?.map((choice) => choice.finish_reason ?? "unknown")
.filter((reason): reason is string => Boolean(reason)),
"gen_ai.usage.input_tokens": payload.usage?.prompt_tokens,
"gen_ai.usage.output_tokens": payload.usage?.completion_tokens,
});
if (typeof content !== "string" || !content.trim()) {
logger.warn(
{
endpoint: endpoint.completionUrl,
provider: endpoint.provider ?? 'default',
},
"[LLM] Empty response from endpoint",
);
return null;
}
return {
content: content.trim(),
endpoint: endpoint.completionUrl,
};
},
);
if (!llmResult) {
await this.circuit.recordFailure(endpoint.completionUrl);
continue;
}
await this.circuit.recordSuccess(endpoint.completionUrl);
return llmResult;
} catch (error) {
await this.circuit.recordFailure(endpoint.completionUrl);
logger.warn(
{
endpoint: endpoint.completionUrl,
provider: endpoint.provider ?? 'default',
error: error instanceof Error ? error.message : String(error),
},
"[LLM] Request error",
);
continue;
}
}
logger.warn("[LLM] All endpoints failed");
return null;
}
hasEndpoints(): boolean {
return this.endpoints.length > 0;
}
}
+42
View File
@@ -0,0 +1,42 @@
import type { GarnetClient } from '@common/garnet';
export interface ChatMessage {
role: "system" | "user" | "assistant";
content: string;
}
export interface ChatCompletionRequest {
model: string;
messages: ChatMessage[];
max_tokens: number;
temperature: number;
response_format?: { type: string } | undefined;
}
export interface ChatCompletionResponse {
model?: string;
choices?: Array<{
finish_reason?: string | null;
message?: {
content?: string | null;
};
}>;
usage?: {
completion_tokens?: number;
prompt_tokens?: number;
total_tokens?: number;
};
}
export interface LlmEndpointConfig {
completionUrl: string;
healthUrl: string;
provider?: "default" | "cliproxy" | undefined;
}
export interface LlmClientOptions {
endpoints: Array<string | { url: string; provider?: "default" | "cliproxy" }>;
garnetClient?: GarnetClient | undefined;
apiKey?: string | undefined;
model?: string | undefined;
}
+221
View File
@@ -0,0 +1,221 @@
import { loadEnvironmentFromNodeEnv } from "./common/env-loader.js";
import { getServiceName } from "./config.js";
import type { GarnetClient } from "./common/garnet.js";
import type { NatsClient } from "./common/nats.js";
loadEnvironmentFromNodeEnv();
const { getLogger, initLogger } = await import("./observability/logger.js");
initLogger();
const logger = getLogger();
const { initTracing, shutdownTracing } = await import(
"./observability/tracing.js"
);
initTracing();
const { GarnetClient: RuntimeGarnetClient } = await import(
"./common/garnet.js"
);
const { NatsClient: RuntimeNatsClient } = await import("./common/nats.js");
const { Agent } = await import("./agent/index.js");
const { ConversationStore } = await import("./conversation/index.js");
const { OnboardingSkill } = await import("./skills/onboarding/index.js");
const { LlmClient } = await import("./llm/index.js");
const { getRawSecret, getSecret } = await import("./common/secret-manager.js");
const { initMongoDB, closeMongoDB } = await import("./common/mongodb.js");
const { RoomContextService } = await import("./room-context/index.js");
function firstNonEmpty(
...values: Array<string | null | undefined>
): string | undefined {
for (const value of values) {
if (value?.trim()) {
return value;
}
}
return undefined;
}
function parseEndpointList(
...values: Array<string | null | undefined>
): string[] {
const items: string[] = [];
for (const value of values) {
if (!value?.trim()) continue;
for (const item of value.split(/[\n,]/u)) {
const trimmed = item.trim();
if (trimmed) items.push(trimmed);
}
}
return [...new Set(items)];
}
function toProviderEndpoints(
urls: string[],
provider?: "default" | "cliproxy",
): Array<string | { url: string; provider?: "default" | "cliproxy" }> {
if (!provider || provider === "default") {
return urls;
}
return urls.map((url) => ({ url, provider }));
}
function formatEndpointList(
endpoints: Array<string | { url: string; provider?: "default" | "cliproxy" }>,
): string {
return endpoints
.map((endpoint) =>
typeof endpoint === "string"
? endpoint
: `${endpoint.provider ?? "default"}:${endpoint.url}`,
)
.join(", ");
}
function installShutdownHooks(
shutdown: (reason: string, error?: unknown) => Promise<void>,
): void {
let shuttingDown = false;
const runShutdown = async (
reason: string,
error?: unknown,
): Promise<void> => {
if (shuttingDown) return;
shuttingDown = true;
if (error) {
logger.error({ err: error }, `[Shutdown] ${reason}`);
} else {
logger.info(`[Shutdown] ${reason}`);
}
try {
await shutdown(reason, error);
} catch (shutdownError) {
logger.error({ err: shutdownError }, "[Shutdown] Cleanup failed");
} finally {
process.exit(error ? 1 : 0);
}
};
for (const signal of ["SIGINT", "SIGTERM"] as const) {
process.once(signal, () => {
void runShutdown(signal);
});
}
process.once("uncaughtException", (error) => {
void runShutdown("uncaughtException", error);
});
process.once("unhandledRejection", (reason) => {
void runShutdown("unhandledRejection", reason);
});
}
async function bootstrap(): Promise<void> {
const serviceName = getServiceName();
const natsClient: NatsClient = new RuntimeNatsClient();
await natsClient.connect();
const garnetClient: GarnetClient = new RuntimeGarnetClient();
await garnetClient.connect();
// LLM Client setup
const cliProxyEndpoints = parseEndpointList(
getRawSecret("CLI_PROXY_API_URLS"),
process.env["CLI_PROXY_API_URLS"],
);
const generalLlmEndpoints = parseEndpointList(
getRawSecret("AGENT_LLM_API_URLS"),
process.env["AGENT_LLM_API_URLS"],
getRawSecret("LLAMA_SERVER_API_URL"),
process.env["LLAMA_SERVER_API_URL"],
);
const llmEndpoints = [
...toProviderEndpoints(cliProxyEndpoints, "cliproxy"),
...toProviderEndpoints(generalLlmEndpoints),
];
const llmApiKey = firstNonEmpty(
getRawSecret("CLI_PROXY_API_KEY"),
process.env["CLI_PROXY_API_KEY"],
getRawSecret("AGENT_LLM_API_KEY"),
process.env["AGENT_LLM_API_KEY"],
getRawSecret("LLAMA_SERVER_API_KEY"),
process.env["LLAMA_SERVER_API_KEY"],
);
const llmModel = firstNonEmpty(
getRawSecret("CLI_PROXY_LLM_MODEL"),
process.env["CLI_PROXY_LLM_MODEL"],
getRawSecret("AGENT_LLM_MODEL"),
process.env["AGENT_LLM_MODEL"],
);
const llmClient = new LlmClient({
endpoints: llmEndpoints,
garnetClient,
apiKey: llmApiKey,
model: llmModel,
});
if (llmEndpoints.length > 0) {
logger.info(
{ endpoints: formatEndpointList(llmEndpoints) },
"✓ LLM endpoints configured",
);
} else {
logger.warn("[LLM] No endpoints configured — all responses will use templates");
}
// MongoDB + RoomContextService setup (optional)
let roomContextService: InstanceType<typeof RoomContextService> | undefined;
const mongoConnectionString = firstNonEmpty(
getSecret("MONGODB_CONNECTION_STRING"),
process.env["MONGODB_CONNECTION_STRING"],
);
if (mongoConnectionString) {
await initMongoDB(mongoConnectionString);
// 시크릿의 projectId를 환경변수로 전파 (config.ts에서 참조)
const mongoProjectId = firstNonEmpty(
getSecret("MONGODB_PROJECT_ID"),
process.env["MONGODB_PROJECT_ID"],
);
if (mongoProjectId) {
process.env["MONGODB_PROJECT_ID"] = mongoProjectId;
}
roomContextService = new RoomContextService();
logger.info("✓ MongoDB connected (room context enabled)");
} else {
logger.warn("[MongoDB] No connection string configured — room context disabled");
}
// Agent setup
const conversationStore = new ConversationStore(garnetClient);
const agent = new Agent(natsClient, conversationStore);
// Register skills
const onboardingSkill = new OnboardingSkill(garnetClient, llmClient, roomContextService);
agent.registerSkill(onboardingSkill);
installShutdownHooks(async () => {
await natsClient.close();
await garnetClient.close();
await closeMongoDB();
await shutdownTracing();
});
await agent.start();
logger.info(`✓ ${serviceName} bootstrapped`);
}
try {
await bootstrap();
} catch (error) {
logger.error({ err: error }, "[Bootstrap] Fatal startup error");
await shutdownTracing();
process.exitCode = 1;
}
+49
View File
@@ -0,0 +1,49 @@
import { AsyncLocalStorage } from 'node:async_hooks';
import type { Logger } from 'pino';
import { getLogger } from './logger.js';
export interface RequestContext {
chatroomId: string;
deadlineAt?: string;
logger: Logger;
requestId: string;
skill: string;
startedAt: string;
trigger: string;
userId: string;
}
const requestContextStorage = new AsyncLocalStorage<RequestContext>();
export function runWithContext<T>(
context: Omit<RequestContext, 'logger'> & { logger?: Logger },
fn: () => T,
): T {
const logger =
context.logger ??
getLogger({
chatroomId: context.chatroomId,
requestId: context.requestId,
skill: context.skill,
trigger: context.trigger,
userId: context.userId,
});
return requestContextStorage.run(
{
...context,
logger,
},
fn,
);
}
export function getContext(): RequestContext | undefined {
return requestContextStorage.getStore();
}
export function getRequestLogger(): Logger {
return getContext()?.logger ?? getLogger();
}
+77
View File
@@ -0,0 +1,77 @@
import pino, { type Logger } from 'pino';
import { KNOWN_SECRET_KEYS } from '@common/known-secret-keys';
import { getLogLevel, getNodeEnv, getServiceName } from '../config.js';
type RequestBindings = {
chatroomId?: string;
requestId?: string;
skill?: string;
trigger?: string;
userId?: string;
};
function buildRedactionPaths(): string[] {
const commonPaths = [
'authorization',
'headers.authorization',
'req.headers.authorization',
'request.headers.authorization',
];
const secretPaths = KNOWN_SECRET_KEYS.flatMap((key) => [
key,
`env.${key}`,
`secrets.${key}`,
`rawSecrets.${key}`,
`request.${key}`,
`response.${key}`,
]);
return [...commonPaths, ...secretPaths];
}
function createLogger(): Logger {
const nodeEnv = getNodeEnv();
const usePretty = nodeEnv !== 'prod';
const transport = usePretty
? pino.transport({
target: 'pino-pretty',
options: {
colorize: nodeEnv === 'dev',
ignore: 'pid,hostname',
singleLine: true,
translateTime: 'SYS:standard',
},
})
: undefined;
return pino(
{
base: {
env: nodeEnv,
service: getServiceName(),
},
level: getLogLevel(),
redact: {
censor: '[REDACTED]',
paths: buildRedactionPaths(),
},
},
transport,
);
}
export let logger: Logger = createLogger();
export function initLogger(): Logger {
logger = createLogger();
return logger;
}
export function getLogger(bindings?: RequestBindings): Logger {
if (!bindings) {
return logger;
}
return logger.child(bindings);
}
+73
View File
@@ -0,0 +1,73 @@
import {
SpanStatusCode,
trace,
type Attributes,
type Span,
} from '@opentelemetry/api';
import { getServiceName } from '../config.js';
function compactAttributes(attributes?: Attributes): Attributes {
if (!attributes) {
return {};
}
return Object.fromEntries(
Object.entries(attributes).filter(([, value]) => value !== undefined),
);
}
export async function withSpan<T>(
name: string,
attributes: Attributes | undefined,
fn: (span: Span) => Promise<T> | T,
): Promise<T> {
const tracer = trace.getTracer(getServiceName());
return tracer.startActiveSpan(name, async (span) => {
span.setAttributes(compactAttributes(attributes));
try {
const result = await fn(span);
span.setStatus({ code: SpanStatusCode.OK });
return result;
} catch (error) {
span.setStatus({
code: SpanStatusCode.ERROR,
message: error instanceof Error ? error.message : String(error),
});
span.recordException(error instanceof Error ? error : new Error(String(error)));
throw error;
} finally {
span.end();
}
});
}
export function withSkillSpan<T>(
skillName: string,
attributes: Attributes | undefined,
fn: (span: Span) => Promise<T> | T,
): Promise<T> {
return withSpan(`skill.${skillName}.handle`, attributes, fn);
}
export function withClassifierSpan<T>(
attributes: Attributes | undefined,
fn: (span: Span) => Promise<T> | T,
): Promise<T> {
return withSpan('classifier.run', attributes, fn);
}
export function withToolSpan<T>(
toolName: string,
attributes: Attributes | undefined,
fn: (span: Span) => Promise<T> | T,
): Promise<T> {
return withSpan(`tool.${toolName}`, attributes, fn);
}
export function withLlmSpan<T>(
attributes: Attributes | undefined,
fn: (span: Span) => Promise<T> | T,
): Promise<T> {
return withSpan('llm.chat_completion', attributes, fn);
}
+66
View File
@@ -0,0 +1,66 @@
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import {
ConsoleSpanExporter,
ParentBasedSampler,
TraceIdRatioBasedSampler,
} from '@opentelemetry/sdk-trace-base';
import { getOtelExporter, getOtelSamplingRatio, getServiceName } from '../config.js';
import { getLogger } from './logger.js';
let sdk: NodeSDK | null = null;
let started = false;
export function initTracing(): void {
if (started) {
return;
}
process.env['OTEL_SERVICE_NAME'] ??= getServiceName();
const logger = getLogger();
const exporter =
getOtelExporter() === 'stdout' ? new ConsoleSpanExporter() : new ConsoleSpanExporter();
sdk = new NodeSDK({
instrumentations: [getNodeAutoInstrumentations()],
sampler: new ParentBasedSampler({
root: new TraceIdRatioBasedSampler(getOtelSamplingRatio()),
}),
traceExporter: exporter,
});
try {
sdk.start();
started = true;
logger.debug(
{
exporter: getOtelExporter(),
samplingRatio: getOtelSamplingRatio(),
},
'[Tracing] Initialized',
);
} catch (error) {
logger.warn(
{
err: error,
},
'[Tracing] Initialization failed',
);
sdk = null;
}
}
export async function shutdownTracing(): Promise<void> {
if (!sdk) {
return;
}
try {
await sdk.shutdown();
} finally {
sdk = null;
started = false;
}
}
+2
View File
@@ -0,0 +1,2 @@
export { RoomContextService } from "./room-context-service.js";
export type { RoomMessage } from "./types.js";
+112
View File
@@ -0,0 +1,112 @@
import mongoose, { Schema } from "mongoose";
import { getMongoConnection } from "@common/mongodb";
import type { RoomMessage } from "./types.js";
import { getMongoDbProjectId, getRoomContextLimit } from "../config.js";
interface EventDocument {
projectId: mongoose.Types.ObjectId;
eventType: string;
category: string;
chatroomId?: string;
senderId?: string;
data: Record<string, unknown>;
timestamp: Date;
}
const EventSchema = new Schema<EventDocument>(
{
projectId: { type: Schema.Types.ObjectId, required: true },
eventType: { type: String, required: true },
category: { type: String, required: true },
chatroomId: { type: String },
senderId: { type: String },
data: { type: Schema.Types.Mixed, required: true },
timestamp: { type: Date, required: true },
},
{ strict: false },
);
function asRecord(value: unknown): Record<string, unknown> {
return typeof value === "object" && value !== null
? (value as Record<string, unknown>)
: {};
}
function extractMessageText(data: Record<string, unknown>): string | null {
const body = asRecord(data["body"]);
const chatLog = asRecord(body["chatLog"]);
const text =
(typeof chatLog["message"] === "string" ? chatLog["message"] : null) ??
(typeof body["message"] === "string" ? body["message"] : null);
return text?.trim() || null;
}
function extractNickname(data: Record<string, unknown>): string {
const body = asRecord(data["body"]);
const nickname = body["authorNickname"];
return typeof nickname === "string" && nickname.trim()
? nickname.trim()
: "알 수 없음";
}
export class RoomContextService {
private model: mongoose.Model<EventDocument> | null = null;
private getModel(): mongoose.Model<EventDocument> {
if (this.model) return this.model;
const connection = getMongoConnection();
if (connection.models["LOCOEvent"]) {
this.model = connection.models["LOCOEvent"] as mongoose.Model<EventDocument>;
} else {
this.model = connection.model<EventDocument>(
"LOCOEvent",
EventSchema,
"events",
);
}
return this.model;
}
async getRecentMessages(
chatroomId: string,
limit?: number,
): Promise<RoomMessage[]> {
const effectiveLimit = limit ?? getRoomContextLimit();
const model = this.getModel();
const filter: Record<string, unknown> = {
chatroomId,
category: "message.received",
};
const projectId = getMongoDbProjectId();
if (projectId) {
filter["projectId"] = new mongoose.Types.ObjectId(projectId);
}
const docs = await model
.find(filter)
.sort({ timestamp: -1 })
.limit(effectiveLimit)
.lean()
.exec();
const messages: RoomMessage[] = [];
for (const doc of docs) {
const text = extractMessageText(doc.data);
if (!text) continue;
messages.push({
senderId: doc.senderId ?? "",
nickname: extractNickname(doc.data),
message: text,
timestamp: doc.timestamp,
});
}
// 시간순 정렬 (오래된 것 먼저)
messages.reverse();
return messages;
}
}
+6
View File
@@ -0,0 +1,6 @@
export interface RoomMessage {
senderId: string;
nickname: string;
message: string;
timestamp: Date;
}
+5
View File
@@ -0,0 +1,5 @@
export { OnboardingSkill } from "./skill.js";
export type {
OnboardingSession,
OnboardingStatus,
} from "./types.js";
+105
View File
@@ -0,0 +1,105 @@
/**
* @deprecated Phase 2에서 classifier 내부 호환용으로만 유지한다.
* Phase 2 PR 2b에서 golden set 확보 후 제거 예정.
*/
/**
* 명확하게 봇에게 향하지 않은 메시지를 사전 필터링한다.
* 보수적으로 동작 — 확실한 경우만 true를 반환한다.
*/
export function shouldSkipMessage(userMessage: string): boolean {
const trimmed = userMessage.trim();
if (!trimmed) return true;
// @멘션으로 시작하는 메시지 (다른 유저에게 하는 말)
if (/^@\S+/u.test(trimmed)) {
return true;
}
// 순수 리액션/감탄 문자열 (ㅋㅋㅋ, ㅎㅎ, ㅡㅡ, ㅜㅜ, ㅇㅇ 등)
if (/^[ㅋㅎㅡㅜㅠㅇㄴㄷㅈ.?!~ㅉ]+$/u.test(trimmed)) {
return true;
}
return false;
}
export type LightweightIntent = "greeting" | "acknowledgement";
const ONBOARDING_KEYWORDS = [
"닉네임",
"닉변",
"이름",
"형식",
"하트",
"인증",
"프로필",
"사진",
"스크린샷",
"스샷",
"디스코드",
"discord",
"디코",
"온보딩",
"가입",
"등록",
"절차",
"방법",
"어떻게",
"뭐해",
"뭐 해",
"해야",
"오류",
"왜",
"어디",
"질문",
"도움",
];
function hasOnboardingKeyword(userMessage: string): boolean {
const lower = userMessage.toLowerCase();
return ONBOARDING_KEYWORDS.some((keyword) => lower.includes(keyword));
}
export function detectLightweightIntent(
userMessage: string,
): LightweightIntent | null {
const trimmed = userMessage.trim();
if (!trimmed || hasOnboardingKeyword(trimmed)) {
return null;
}
if (trimmed.length > 24) {
return null;
}
const greetingPattern =
/^(안녕(?:하세요)?|안뇽|하이|반갑(?:습니다|어요)|처음\s*왔(?:어요|습니다)|잘\s*부탁(?:드려요|드립니다))(?:[\s!?.~,ㅋㅎㅠㅜ]*)$/u;
if (greetingPattern.test(trimmed)) {
return "greeting";
}
const acknowledgementPattern =
/^(감사(?:합니다|해요|해용|해)|고마워(?:요)?|감사요|넵|네|넹|예|알겠(?:어요|습니다)|확인했(?:어요|습니다)|오케이|오키|ㅇㅋ)(?:[\s!?.~,ㅋㅎㅠㅜ]*)$/u;
if (acknowledgementPattern.test(trimmed)) {
return "acknowledgement";
}
return null;
}
export function isRemainingStatusQuestion(userMessage: string): boolean {
const trimmed = userMessage.trim();
if (!trimmed) {
return false;
}
const detailRequestPattern =
/(어떻게|어디|방법|어케|뭔지|뭐야|무슨\s*뜻|왜|예시|형식)/u;
if (detailRequestPattern.test(trimmed)) {
return false;
}
const statusPattern =
/(진행\s*상황|현황|상태|남은\s*(거|것|게|절차|단계|일)|뭐\s*남|뭐가\s*남|이제\s*뭐|얼마나\s*남|남았(?:지|나요|어요)?)/u;
return statusPattern.test(trimmed);
}
@@ -0,0 +1,290 @@
import type { NicknameIssue, OnboardingSession } from "./types.js";
function pickRandom(items: [string, ...string[]]): string {
return items[Math.floor(Math.random() * items.length)] ?? items[0];
}
const VALID_GENDERS = new Set(["남", "여"]);
const VALID_TIERS = new Set(["GM", "I", "B", "S", "G", "P", "E", "D", "M", "C", "U"]);
export function analyzeNicknameIssues(nickname: string): NicknameIssue[] {
const parts = nickname.trim().split("/");
const issues: NicknameIssue[] = [];
if (parts.length === 3) {
const [, age, third] = parts;
if (age && !/^\d{2}$/u.test(age)) {
issues.push({
kind: "invalid-age",
message: "나이를 두 자리 숫자로 입력해주세요 (예: 25)",
suggestion: "95",
});
}
if (third) {
const hasGender = VALID_GENDERS.has(third.charAt(0));
const rest = third.slice(1);
if (hasGender && rest.length > 0 && !VALID_TIERS.has(rest)) {
issues.push({
kind: "unknown-tier",
message: `성별 뒤의 '${rest}'를 제거하고, 티어 코드를 '/'로 구분해서 추가해주세요 (예: ${third.charAt(0)}/D)`,
suggestion: `${third.charAt(0)}/D`,
});
} else if (hasGender && rest.length > 0) {
issues.push({
kind: "wrong-separator",
message: `성별과 티어 코드는 '/'로 구분해서 입력해주세요 (예: ${third.charAt(0)}/${rest})`,
suggestion: `${third.charAt(0)}/${rest}`,
});
} else if (!hasGender) {
issues.push({
kind: "missing-gender",
message: "성별(남/여)과 티어 코드를 '/'로 구분해서 입력해주세요",
});
} else {
issues.push({
kind: "missing-tier",
message: `티어 코드를 '/'로 구분해서 추가해주세요 (예: ${third}/D)`,
suggestion: `${third}/D`,
});
}
} else {
issues.push({
kind: "other",
message: "성별과 티어 코드가 누락되었어요",
});
}
return issues;
}
if (parts.length !== 4) {
issues.push({
kind: "wrong-separator",
message: `'/'로 구분된 4개 항목(이름/나이/성별/티어)이 필요해요. 현재 ${parts.length}개입니다.`,
});
return issues;
}
const [, age, gender, tier] = parts;
if (!age || !/^\d{2}$/u.test(age)) {
issues.push({
kind: "invalid-age",
message: "나이를 두 자리 숫자로 입력해주세요 (예: 25)",
suggestion: "95",
});
}
if (!gender || !VALID_GENDERS.has(gender)) {
issues.push({
kind: "missing-gender",
message: "성별을 '남' 또는 '여'로 입력해주세요",
});
}
if (!tier || !VALID_TIERS.has(tier)) {
issues.push({
kind: "unknown-tier",
message: "티어 코드(GM,I,B,S,G,P,E,D,M,C,U 중 하나)를 입력해주세요",
});
}
return issues;
}
export function getWelcomeMessage(nickname: string): string {
return pickRandom([
`${nickname}님 환영합니다! 새내기 등록은 닉네임 변경과 하트 인증 두 가지를 진행하시면 돼요.\n\n` +
`1. 닉네임 변경: 이름/나이/성별/티어 형식 (예: 홍길동/25/남/G)\n` +
`2. 하트 인증: 채팅방 프로필 하트를 빨간색으로 만들고 원본 스크린샷 전송\n\n` +
`궁금한 점 있으시면 편하게 물어봐 주세요!`,
`${nickname}님 반갑습니다! 톡 게시글의 공지를 참고하셔서 닉네임 변경과 하트 인증을 진행해 주세요.\n\n` +
`닉네임: 이름/나이/성별/티어 형식으로 변경 (예: 홍길동/25/남/G)\n` +
`하트 인증: 프로필 하트 빨간색 상태 원본 스크린샷 전송\n\n` +
`어떤 것부터 시작하시겠어요?`,
`${nickname}님 롤림푸스에 오신 걸 환영해요! 등록 절차를 안내해 드릴게요.\n\n` +
`닉네임을 이름/나이/성별/티어 형식(예: 홍길동/25/남/G)으로 바꿔주시고, ` +
`채팅방 프로필 하트를 빨간색으로 만든 원본 스크린샷을 보내주시면 됩니다. 순서는 상관없어요!`,
]);
}
export function getGreetingMessage(): string {
return pickRandom([
"환영합니다! 반갑습니다.",
"반갑습니다! 어서 오세요.",
"환영해요! 반갑습니다.",
]);
}
export function getAcknowledgementMessage(): string {
return pickRandom([
"네, 편하게 진행해 보시면 돼요.",
"좋아요! 천천히 진행해 주세요.",
"네, 그렇게 해주시면 돼요.",
]);
}
export function getNicknameInvalidMessage(
nickname: string,
_session: OnboardingSession | null,
): string {
const issues = analyzeNicknameIssues(nickname);
if (issues.length === 0) {
return pickRandom([
`@${nickname}님 닉네임 형식을 한번 확인해 주세요. 올바른 형식은 이름/나이/성별/티어예요. (예: 홍길동/25/남/G)`,
`@${nickname}님 닉네임이 형식에 맞지 않는 것 같아요. 이름/나이(두자리)/성별(남,여)/티어코드 형식으로 변경해 주세요!`,
]);
}
const prefix = pickRandom([
`@${nickname}님 닉네임에서 수정할 부분이 있어요!`,
`@${nickname}님 닉네임을 조금만 수정해 주세요!`,
]);
return `${prefix}\n${issues.map((issue) => issue.message).join("\n")}`;
}
export function getNicknameFormatMessage(): string {
return pickRandom([
"닉네임 형식은 이름/출생 연도 두 자리/성별/티어예요. 예를 들면 홍길동/95/여/D처럼 쓰시면 돼요.",
"닉네임은 이름/출생 연도 두 자리/성별/티어 형식으로 입력해 주시면 돼요! 예: 홍길동/95/남/G",
]);
}
export function getHeartGuideMessage(): string {
return pickRandom([
'채팅방 오른쪽 상단 메뉴 버튼에서 "커버 보기"로 들어가 하트를 빨간색으로 바꾼 뒤, 편집 없이 원본 스크린샷을 올려주시면 돼요.',
"채팅방 프로필에서 하트를 눌러 빨간색으로 만든 다음, 그 화면이 보이게 원본 스크린샷을 보내주시면 인증돼요.",
]);
}
export function getHeartLocationMessage(): string {
return pickRandom([
'채팅방 오른쪽 상단 메뉴 버튼을 누르면 "커버 보기"가 보여요. 거기서 프로필과 하트를 확인하실 수 있어요.',
'오른쪽 상단 메뉴 버튼으로 들어가 "커버 보기"를 열면 하트 위치를 확인하실 수 있어요.',
]);
}
export function getAgeRequirementMessage(): string {
return pickRandom([
"롤림푸스는 27세 이상만 가입이 가능해요.",
"가입 가능 연령은 27세 이상이에요.",
]);
}
export function getPhotoFailedMessage(nickname: string): string {
return pickRandom([
`${nickname}님 하트 인증 사진이 인식되지 않았어요. ` +
`채팅방 프로필에서 하트를 눌러 빨간색으로 만든 후, 편집 없이 원본 스크린샷을 보내주시면 됩니다!`,
`${nickname}님 하트 인증이 아직 확인되지 않았어요. ` +
`프로필 하트가 빨간색인 상태의 스크린샷을 편집 없이 원본 그대로 다시 보내주시겠어요?`,
]);
}
export function getProgressMessage(
nickname: string,
session: OnboardingSession,
): string {
const nicknameIcon = session.nicknameVerified ? "v" : "x";
const photoIcon = session.photoVerified ? "v" : "x";
let nextStep = "";
if (!session.nicknameVerified && !session.photoVerified) {
nextStep = pickRandom([
"\n\n톡 게시글의 공지를 참고하셔서 닉네임 변경과 하트 인증을 진행해 주세요!",
"\n\n아직 두 가지 모두 남아있어요. 어떤 것부터 시작하시겠어요?",
]);
} else if (!session.nicknameVerified) {
nextStep = pickRandom([
"\n\n닉네임 변경만 완료하시면 돼요! 이름/나이/성별/티어 형식으로 변경해 주세요.",
"\n\n하트 인증은 완료됐어요! 닉네임만 변경해 주시면 끝이에요.",
]);
} else if (!session.photoVerified) {
nextStep = pickRandom([
"\n\n하트 인증만 남았어요! 프로필 하트를 빨간색으로 만든 스크린샷을 보내주세요.",
"\n\n닉네임은 완료됐어요! 하트 인증 스크린샷만 보내주시면 끝이에요.",
]);
}
return (
`${nickname}님 현재 진행상황: 닉네임 [${nicknameIcon}] | 하트인증 [${photoIcon}]` +
nextStep
);
}
export function getTimeoutWarningMessage(nickname: string): string {
return pickRandom([
`${nickname}님 등록 시간이 얼마 남지 않았어요! 아직 완료하지 못한 절차가 있다면 서둘러 주세요.`,
`${nickname}님 등록 마감이 가까워지고 있어요. 남은 절차를 빠르게 진행해 주세요!`,
]);
}
export function getCompletedMessage(nickname: string): string {
return pickRandom([
`${nickname}님 모든 절차가 완료되었어요! 즐거운 롤림푸스 생활 되세요.`,
`${nickname}님 등록이 모두 끝났어요! 앞으로 롤림푸스에서 즐거운 시간 보내세요.`,
]);
}
export function getGenericHelpMessage(
nickname: string,
session: OnboardingSession | null,
): string {
if (!session || (!session.nicknameVerified && !session.photoVerified)) {
return pickRandom([
`톡 게시글의 공지를 참고하셔서 닉네임 변경과 하트 인증을 진행해 주세요!`,
`닉네임 변경과 하트 인증 두 가지를 완료하시면 돼요. 톡 게시글의 공지를 확인해 주세요!`,
]);
}
if (!session.nicknameVerified) {
return pickRandom([
`닉네임을 이름/나이/성별/티어 형식으로 변경해 주세요! (예: 홍길동/25/남/G)`,
`닉네임 변경이 아직 안 됐어요. 이름/나이/성별/티어 형식으로 바꿔주시면 돼요!`,
]);
}
if (!session.photoVerified) {
return pickRandom([
`하트 인증만 남았어요! 채팅방 프로필 하트를 빨간색으로 만든 스크린샷을 보내주세요.`,
`하트 인증 스크린샷만 보내주시면 끝이에요! 프로필 하트를 빨간색으로 만들어 주세요.`,
]);
}
return `${nickname}님 두 절차가 모두 확인되면 디스코드 권한이 자동으로 부여돼요!`;
}
export function getRemainingStatusMessage(
session: OnboardingSession | null,
): string {
if (!session || (!session.nicknameVerified && !session.photoVerified)) {
return "이제 닉네임 변경과 방 하트 인증 두 가지가 남아 있어요.";
}
if (!session.nicknameVerified) {
return "이제 닉네임 변경만 남았어요.";
}
if (!session.photoVerified) {
return "이제 방 하트 인증만 남았어요.";
}
return "이제 새내기 등록 절차는 모두 완료됐어요.";
}
export function getDiscordMessage(
nickname: string,
session: OnboardingSession | null,
): string {
if (session?.nicknameVerified && session?.photoVerified) {
return pickRandom([
`${nickname}님 두 절차 모두 완료되셨어요! 디스코드 서버에 입장해서 서버 프로필을 설정해 주시면 봇이 자동으로 권한을 부여해 드려요.`,
`${nickname}님 닉네임과 하트 인증 모두 완료됐어요! 이제 디스코드 서버에 입장하신 후 서버 프로필을 설정하시면 권한이 자동 부여돼요.`,
]);
}
return pickRandom([
`${nickname}님 닉네임 변경과 하트 인증을 먼저 완료해 주셔야 디스코드 안내를 드릴 수 있어요!`,
`${nickname}님 디스코드 권한은 닉네임 변경과 하트 인증을 모두 완료하신 후에 안내드릴게요!`,
]);
}
@@ -0,0 +1,85 @@
import { describe, expect, it } from "vitest";
import { PromptBuilder } from "./builder.js";
import type { DerivedState } from "../state/onboarding-state.js";
import type { OnboardingSession, PromptContext } from "../types.js";
function makeDerived(
overrides?: Partial<DerivedState>,
): DerivedState {
return {
phase: { kind: "photo-pending" },
intent: { kind: "photo-question" },
shouldRespond: true,
responseMode: "llm",
suggestedMaxTokens: 256,
allowShortResponse: false,
tier: 0,
...overrides,
};
}
function makeSession(
overrides?: Partial<OnboardingSession>,
): OnboardingSession {
return {
chatroomId: "room-1",
deadlineAt: "2026-04-16T12:00:00.000Z",
joinedAt: "2026-04-16T10:00:00.000Z",
lastEventAt: "2026-04-16T10:30:00.000Z",
nickname: "프리리/95/여/D",
nicknameVerified: true,
photoVerified: false,
status: "pending",
userId: "user-1",
...overrides,
};
}
function makeContext(
overrides?: Partial<PromptContext>,
): PromptContext {
return {
blackboard: {
flaggedIssues: [],
openQuestions: [],
recentNicknameAttempts: [],
toneMemory: {},
},
conversationHistory: Array.from({ length: 7 }, (_, index) => ({
role: index % 2 === 0 ? "user" : "assistant",
content: `message-${index + 1}`,
timestamp: `2026-04-16T10:0${index}:00.000Z`,
})),
summary: "이전 대화 요약",
userMessage: "하트 인증은 어떻게 해요?",
...overrides,
};
}
describe("PromptBuilder", () => {
it("includes intent-matched examples in system prompt", () => {
const messages = PromptBuilder.forDerived(
makeDerived(),
makeSession(),
makeContext(),
).build();
expect(messages[0]?.role).toBe("system");
expect(messages[0]?.content).toContain("하트 인증이 뭐예요?");
expect(messages[0]?.content).not.toContain("나이 제한 있나요?");
});
it("limits prompt history to the latest five turns when summary exists", () => {
const messages = PromptBuilder.forDerived(
makeDerived(),
makeSession(),
makeContext(),
).build();
expect(messages).toHaveLength(7);
expect(messages[1]?.content).toBe("message-3");
expect(messages[5]?.content).toBe("message-7");
expect(messages[0]?.content).toContain("이전 대화 요약");
});
});
+53
View File
@@ -0,0 +1,53 @@
import type { ChatMessage } from "@llm/types";
import type { DerivedState } from "../state/onboarding-state.js";
import type { OnboardingSession, PromptContext } from "../types.js";
import {
contextLayer,
examplesLayer,
personaLayer,
policyLayer,
stateLayer,
} from "./layers.js";
export class PromptBuilder {
private constructor(
private readonly derived: DerivedState,
private readonly session: OnboardingSession | null,
private readonly context: PromptContext,
) {}
static forDerived(
derived: DerivedState,
session: OnboardingSession | null,
context: PromptContext,
): PromptBuilder {
return new PromptBuilder(derived, session, context);
}
build(): ChatMessage[] {
const promptHistory = this.context.summary
? this.context.conversationHistory.slice(-5)
: this.context.conversationHistory;
const promptContext: PromptContext = {
...this.context,
conversationHistory: promptHistory,
};
const systemPrompt = [
personaLayer(),
policyLayer(this.derived.intent),
stateLayer(this.session, this.derived),
examplesLayer(this.derived.intent),
contextLayer(promptContext),
].join("\n\n");
return [
{ role: "system", content: systemPrompt },
...promptHistory.map((message) => ({
role: message.role,
content: message.content,
})),
{ role: "user", content: this.context.userMessage },
];
}
}
+105
View File
@@ -0,0 +1,105 @@
import type { Intent } from "../state/onboarding-state.js";
import type { Example } from "../types.js";
export const EXAMPLES_BY_INTENT: Record<Intent["kind"], Example[]> = {
greeting: [
{
user: "안녕하세요!",
assistant: "환영합니다! 반갑습니다.",
},
{
user: "반갑습니다",
assistant: "반갑습니다! 어서 오세요.",
},
],
acknowledgement: [
{
user: "넵 확인했어요",
assistant: "네, 편하게 진행해 보시면 돼요.",
},
{
user: "감사합니다",
assistant: "좋아요! 천천히 진행해 주세요.",
},
],
"status-question": [
{
user: "이제 뭐 남았지?",
assistant: "이제 방 하트 인증만 남았어요.",
},
{
user: "진행상황 알려줘",
assistant: "아직 닉네임 변경과 방 하트 인증 두 가지가 남아 있어요.",
},
],
"help-how": [
{
user: "하트 인증은 어떻게 해요?",
assistant:
'채팅방 오른쪽 상단 메뉴 버튼에서 "커버 보기"로 들어가 하트를 빨간색으로 바꾼 뒤, 편집 없이 원본 스크린샷을 올려주시면 돼요.',
},
{
user: "닉네임 형식 예시 알려줘",
assistant:
"닉네임은 이름/출생 연도 두 자리/성별/티어 형식이에요. 예를 들면 홍길동/95/여/D처럼 쓰시면 돼요.",
},
],
"help-where": [
{
user: "하트 어디서 바꿔요?",
assistant:
'채팅방 오른쪽 상단 메뉴 버튼을 누르면 "커버 보기"가 보여요. 거기서 프로필과 하트를 확인하실 수 있어요.',
},
],
"nickname-question": [
{
user: "닉네임이 왜 안 돼요?",
assistant:
"티어는 한 글자 코드로 넣어야 해요. 예를 들면 D처럼 바꿔주시면 돼요.",
},
{
user: "닉네임 형식이 뭐예요?",
assistant:
"닉네임은 이름/출생 연도 두 자리/성별/티어 형식으로 입력해 주시면 돼요.",
},
],
"photo-question": [
{
user: "하트 인증이 뭐예요?",
assistant:
"채팅방 프로필에서 하트를 빨간색으로 바꾼 뒤, 그 화면이 보이게 원본 스크린샷을 보내주시면 돼요.",
},
],
"discord-question": [
{
user: "디스코드는 언제 들어가요?",
assistant:
"닉네임 변경과 하트 인증을 모두 완료하신 뒤에 디스코드 안내를 받으실 수 있어요.",
},
],
"age-question": [
{
user: "나이 제한 있나요?",
assistant: "롤림푸스는 27세 이상만 가입이 가능해요.",
},
],
chitchat: [
{
user: "오늘 날씨 좋네요",
assistant: "[NO_RESPONSE]",
},
],
"off-topic-to-other": [
{
user: "@프리리 이거 확인해줘",
assistant: "[NO_RESPONSE]",
},
],
unknown: [
{
user: "가입은 어떻게 하나요?",
assistant:
"톡 게시글의 공지를 참고하셔서 닉네임 변경과 하트 인증을 진행해 주세요!",
},
],
};
+194
View File
@@ -0,0 +1,194 @@
import type { ConversationMessage } from "@agent/types";
import type { RoomMessage } from "@room/types";
import type { DerivedState, Intent } from "../state/onboarding-state.js";
import type {
Blackboard,
Example,
OnboardingSession,
PromptContext,
} from "../types.js";
import { EXAMPLES_BY_INTENT } from "./examples.js";
function formatKstTimestamp(value: string | undefined): string {
if (!value) {
return "없음";
}
const timestamp = Date.parse(value);
if (!Number.isFinite(timestamp)) {
return "없음";
}
return new Intl.DateTimeFormat("ko-KR", {
dateStyle: "short",
timeStyle: "short",
timeZone: "Asia/Seoul",
}).format(new Date(timestamp));
}
function formatNicknameStatus(session: OnboardingSession | null): string {
if (!session) {
return "미완료";
}
return session.nicknameVerified
? `완료 (${session.nickname})`
: `미완료 (현재: ${session.nickname})`;
}
function formatPhotoStatus(session: OnboardingSession | null): string {
if (!session) {
return "미완료";
}
return session.photoVerified ? "완료" : "미완료";
}
function formatHistory(history: ConversationMessage[]): string {
if (history.length === 0) {
return "(최근 대화 없음)";
}
return history.map((message) => `${message.role}: ${message.content}`).join("\n");
}
function formatRoomMessages(roomContext?: RoomMessage[]): string {
if (!roomContext || roomContext.length === 0) {
return "(방 분위기 정보 없음)";
}
return roomContext
.slice(-5)
.map((message) => `${message.nickname}: ${message.message}`)
.join("\n");
}
function formatBlackboard(blackboard: Blackboard): string {
const openQuestions =
blackboard.openQuestions.length > 0
? blackboard.openQuestions.join(", ")
: "(없음)";
const flaggedIssues =
blackboard.flaggedIssues.length > 0
? blackboard.flaggedIssues.join(", ")
: "(없음)";
const nicknameAttempts =
blackboard.recentNicknameAttempts.length > 0
? blackboard.recentNicknameAttempts.join(", ")
: "(없음)";
return [
`- lastIntent: ${blackboard.lastIntent ?? "(없음)"}`,
`- openQuestions: ${openQuestions}`,
`- flaggedIssues: ${flaggedIssues}`,
`- recentNicknameAttempts: ${nicknameAttempts}`,
].join("\n");
}
function formatExample(example: Example): string {
return `유저: ${example.user}\n응답: ${example.assistant}`;
}
export function personaLayer(): string {
return `너는 롤림푸스(lolympus) 카카오톡 오픈채팅에서 새내기 등록을 도와주는 친절한 선배야.
처음 온 멤버가 편안하게 등록을 마칠 수 있도록 자연스럽고 정확하게 안내해줘.
[커뮤니티 규칙]
- 가입 가능 연령은 27세 이상이야.
- 새내기 등록은 닉네임 변경과 방 하트 인증 두 가지를 모두 완료하면 돼.
- 닉네임 형식은 이름/출생 연도 두 자리/성별/티어야. 예: 홍길동/95/남/G
- 성별은 남 또는 여, 티어 코드는 GM, I, B, S, G, P, E, D, M, C, U 중 하나야.
- 방 하트 인증은 채팅방 프로필에서 하트를 빨간색으로 바꾼 뒤 편집 없는 원본 스크린샷을 보내는 절차야.
- 디스코드 안내는 닉네임 변경과 하트 인증이 모두 완료된 뒤에만 해줘.`;
}
export function policyLayer(
intent: Intent,
options?: { toolPolicy?: string | undefined },
): string {
const lines = [
"[답변 원칙]",
"- 마지막 메시지에서 직접 물은 내용에만 정확히 답해.",
"- 사용자가 요청하지 않은 다음 단계, 방법, 위치, 예시는 먼저 붙이지 마.",
"- 마크다운 문법, 링크, URL은 쓰지 마.",
'- 온보딩과 무관한 잡담이거나 다른 사람에게 하는 말이면 "[NO_RESPONSE]"만 출력해.',
];
switch (intent.kind) {
case "greeting":
lines.push("- 짧은 인사만 1문장으로 답해.");
break;
case "acknowledgement":
lines.push("- 짧은 확인이나 마무리만 1문장으로 답해.");
break;
case "status-question":
lines.push("- 현재 남은 절차나 완료 상태만 1문장으로 짧게 답해.");
lines.push("- 방법 설명, 위치 설명, 예시는 넣지 마.");
break;
case "help-where":
lines.push("- 위치나 경로만 답하고, 요청하지 않은 다음 단계는 붙이지 마.");
break;
case "help-how":
lines.push("- 사용자가 물은 한 가지 절차의 방법만 답해.");
break;
case "nickname-question":
lines.push("- 닉네임 형식 또는 오류 원인만 답하고 다른 절차는 언급하지 마.");
break;
case "photo-question":
lines.push("- 하트 인증에 대해서만 답하고 다른 절차는 언급하지 마.");
break;
case "discord-question":
lines.push("- 디스코드 질문에만 답해. 완료 전이라면 먼저 온보딩 완료가 필요하다고만 알려줘.");
break;
case "age-question":
lines.push("- 나이 제한만 간단히 답해.");
break;
default:
lines.push("- 질문 범위를 넘어서 먼저 설명하지 마.");
break;
}
if (options?.toolPolicy) {
lines.push(options.toolPolicy);
}
return lines.join("\n");
}
export function stateLayer(
session: OnboardingSession | null,
derived: DerivedState,
): string {
return [
"[현재 유저 상태]",
`- phase: ${derived.phase.kind}`,
`- nickname: ${formatNicknameStatus(session)}`,
`- photo: ${formatPhotoStatus(session)}`,
`- deadline(KST): ${formatKstTimestamp(session?.deadlineAt)}`,
].join("\n");
}
export function examplesLayer(intent: Intent, count = 3): string {
const examples = EXAMPLES_BY_INTENT[intent.kind].slice(0, count);
const rendered = examples.length > 0
? examples.map(formatExample).join("\n\n")
: "(예시 없음)";
return `[응답 예시]\n${rendered}`;
}
export function contextLayer(context: PromptContext): string {
return [
"[최근 요약]",
context.summary ?? "(요약 없음)",
"",
"[최근 대화]",
formatHistory(context.conversationHistory),
"",
"[방 분위기]",
formatRoomMessages(context.roomContext),
"",
"[메모]",
formatBlackboard(context.blackboard),
].join("\n");
}
+577
View File
@@ -0,0 +1,577 @@
import type { AgentRequest, AgentResponse, ConversationMessage } from "@agent/types";
import { getConversationSummaryKey } from "@conv/conversation-store";
import type { GarnetClient } from "@common/garnet";
import { 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 { 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, getMaxResponseLength, 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 type { OnboardingSession, PromptContext } from "./types.js";
const ALLOWED_URL_PATTERNS = [
/discord\.gg\/lolympus/u,
/open\.kakao\.com\/o\/gOscBAEh/u,
];
type LlmTextResult =
| { status: "success"; text: string }
| { status: "no_response" }
| { status: "failed" };
function postProcessResponse(text: string): string {
let processed = text.trim();
// Remove <think> blocks (Qwen thinking mode artifacts)
processed = processed.replace(/<think>[\s\S]*?<\/think>/gu, "").trim();
// Strip URLs not in allowlist
processed = processed.replace(
/https?:\/\/[^\s)}\]]+/gu,
(match) => {
if (ALLOWED_URL_PATTERNS.some((pattern) => pattern.test(match))) {
return match;
}
return "";
},
);
// Clean up double spaces from URL removal
processed = processed.replace(/ +/gu, " ").trim();
// Strip markdown formatting (KakaoTalk is plaintext)
processed = processed.replace(/\*\*(.+?)\*\*/gu, "$1"); // **bold**
processed = processed.replace(/\*(.+?)\*/gu, "$1"); // *italic*
processed = processed.replace(/__(.+?)__/gu, "$1"); // __underline__
processed = processed.replace(/~~(.+?)~~/gu, "$1"); // ~~strike~~
processed = processed.replace(/^#{1,6}\s+/gmu, ""); // ## headings
processed = processed.replace(/^[-*]\s+/gmu, ""); // - or * list items
processed = processed.replace(/`(.+?)`/gu, "$1"); // `inline code`
// Truncate to max length with Korean sentence boundary awareness
const maxLen = getMaxResponseLength();
if (processed.length > maxLen) {
processed = processed.slice(0, maxLen).trimEnd();
// Search backwards for a Korean sentence-ending pattern
const sentenceEndPattern = /(?:세요[.!]?|해요[.!]?|돼요[.!]?|어요[.!]?|아요[.!]?|거든요[.!]?|습니다[.!]?|됩니다[.!]?|니다[.!]?|요[.!]|다[.!]|[.!?])\s*$/u;
// Try progressively shorter substrings to find a sentence boundary
for (let i = processed.length; i > maxLen * 0.5; i--) {
const sub = processed.slice(0, i);
if (sentenceEndPattern.test(sub)) {
processed = sub;
break;
}
}
}
return processed.trim();
}
function isLowQualityResponse(
text: string,
options?: { allowShortResponse?: boolean },
): boolean {
if (!options?.allowShortResponse && text.length < 10) return true;
// Check for excessive repetition (same phrase 3+ times)
const words = text.split(/\s+/u);
if (words.length >= 6) {
const phrases = new Map<string, number>();
for (let i = 0; i < words.length - 1; i++) {
const bigram = `${words[i]} ${words[i + 1]}`;
phrases.set(bigram, (phrases.get(bigram) ?? 0) + 1);
}
for (const count of phrases.values()) {
if (count >= 3) return true;
}
}
return false;
}
export class OnboardingSkill implements Skill {
readonly name = "onboarding";
private readonly classifier: OnboardingIntentClassifier;
private readonly blackboardStore: OnboardingBlackboardStore;
constructor(
private readonly garnetClient: GarnetClient,
private readonly llmClient: LlmClient,
private readonly roomContextService?: RoomContextService,
) {
this.classifier = new OnboardingIntentClassifier(llmClient);
this.blackboardStore = new OnboardingBlackboardStore(garnetClient);
}
canHandle(request: AgentRequest): boolean {
return request.skill === "onboarding";
}
async handle(
request: AgentRequest,
conversationHistory: ConversationMessage[],
): Promise<AgentResponse> {
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");
});
}
return response;
}
private async loadSession(
chatroomId: string,
userId: string,
): Promise<OnboardingSession | null> {
const prefix = getOnboardingSessionKeyPrefix();
const key = `${prefix}:onboarding:${chatroomId}:${userId}`;
return this.garnetClient.getJson<OnboardingSession>(key);
}
private async handleLlm(
request: AgentRequest,
session: OnboardingSession | null,
conversationHistory: ConversationMessage[],
derived: DerivedState,
): Promise<LlmTextResult> {
const messages = await this.buildLlmMessages(
request,
session,
conversationHistory,
derived,
);
return this.generateLlmText(messages, {
allowShortResponse: derived.allowShortResponse,
maxTokens: derived.suggestedMaxTokens,
retryOnLowQuality:
request.trigger === "user-message" && !derived.allowShortResponse,
});
}
private async buildLlmMessages(
request: AgentRequest,
session: OnboardingSession | null,
conversationHistory: ConversationMessage[],
derived: DerivedState,
): Promise<ChatMessage[]> {
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<string | undefined> {
const key = getConversationSummaryKey(chatroomId, userId);
return (await this.garnetClient.getString(key)) ?? undefined;
}
private async rememberTurn(
request: AgentRequest,
derived: DerivedState,
): Promise<void> {
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[],
options?: {
allowShortResponse?: boolean;
maxTokens?: number;
retryOnLowQuality?: boolean;
temperature?: number;
},
): Promise<LlmTextResult> {
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 llmResult = await this.llmClient.chatCompletion(
messages,
requestOptions,
);
if (!llmResult) {
continue;
}
const processed = postProcessResponse(llmResult.content);
if (!processed) {
continue;
}
if (processed.includes("[NO_RESPONSE]")) {
return { status: "no_response" };
}
const qualityOptions =
options?.allowShortResponse !== undefined
? { allowShortResponse: options.allowShortResponse }
: undefined;
if (isLowQualityResponse(processed, qualityOptions)) {
continue;
}
return {
status: "success",
text: processed,
};
}
return { status: "failed" };
}
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",
};
}
}
+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" };
}
+60
View File
@@ -0,0 +1,60 @@
import type { ConversationMessage } from "@agent/types";
import type { RoomMessage } from "@room/types";
export type OnboardingStatus = "pending" | "completed" | "timed_out";
export type NicknameIssueKind =
| "missing-tier"
| "invalid-age"
| "missing-gender"
| "wrong-separator"
| "unknown-tier"
| "other";
export interface NicknameIssue {
kind: NicknameIssueKind;
message: string;
suggestion?: string | undefined;
}
export interface Example {
assistant: string;
user: string;
}
export interface PromptContext {
blackboard: Blackboard;
conversationHistory: ConversationMessage[];
roomContext?: RoomMessage[] | undefined;
summary?: string | undefined;
userMessage: string;
}
export interface Blackboard {
flaggedIssues: string[];
lastIntent?: string | undefined;
lastIntentAt?: string | undefined;
openQuestions: string[];
recentNicknameAttempts: string[];
toneMemory: {
greetedAt?: string | undefined;
thankedAt?: string | undefined;
};
}
export interface OnboardingSession {
chatroomId: string;
completedAt?: string;
deadlineAt: string;
discordMemberId?: string;
joinedAt: string;
lastEventAt: string;
nickname: string;
nicknameVerified: boolean;
nicknameVerifiedAt?: string;
photoVerified: boolean;
photoVerifiedAt?: string;
status: OnboardingStatus;
timedOutAt?: string;
userId: string;
}
+14
View File
@@ -0,0 +1,14 @@
import type {
AgentRequest,
AgentResponse,
ConversationMessage,
} from "@agent/types";
export interface Skill {
readonly name: string;
canHandle(request: AgentRequest): boolean;
handle(
request: AgentRequest,
conversationHistory: ConversationMessage[],
): Promise<AgentResponse>;
}