Outbound Session Mirroring 개선하기

메시지를 보냈는데 정작 대화 기록에는 엉뚱한 곳에 남아있거나 아예 기록되지 않아 당황하신 적 있나요? 특히 여러 채널을 관리할 때 인바운드와 아웃바운드 메시지의 세션이 서로 꼬이면 디버깅이 정말 힘들어지죠. 이번 리팩토링은 아웃바운드 메시지가 타겟 채널 세션에 정확히 미러링되도록 하여 이런 문제를 해결합니다.

필요한 것

• src/infra/outbound/outbound-session.ts 파일 접근 권한
• Slack, Discord, Telegram 등 지원되는 채널 확장 기능
• Gateway API 및 메시지 전송 권한

빠른 시작

아웃바운드 세션 미러링을 적용하는 핵심 단계입니다.

1. 세션 라우팅 헬퍼 활용 resolveOutboundSessionRoute를 사용하여 sessionKey를 빌드하세요. 이 함수는 buildAgentSessionKey를 통해 dmScope와 identityLinks를 조합하여 정확한 타겟 세션을 찾아줍니다.

2. Gateway 전송 시 세션 유추 Gateway를 통해 메시지를 보낼 때 sessionKey를 생략하면 시스템이 타겟과 기본 에이전트를 기반으로 sessionKey를 자동으로 유추하고 세션 엔트리를 생성합니다.

// src/gateway/server-methods/send.ts 예시
// sessionKey가 생략된 경우 자동으로 유추하여 미러링을 수행합니다.
const derivedSessionKey = deriveTargetSessionKey(target, defaultAgent);
ensureOutboundSessionEntry(derivedSessionKey);

문제 해결

메시지가 잘못된 세션에 기록되나요?

이전에는 아웃바운드 전송이 타겟 채널 세션이 아닌 현재 에이전트 세션(도구 세션 키)에 미러링되는 문제가 있었습니다. runMessageAction이 타겟 sessionKey를 파생하여 executeSendAction에 전달하는지 확인하세요.

첫 연락 시 세션 엔트리가 누락되나요?

ensureOutboundSessionEntry가 recordSessionMetaFromInbound를 통해 최소한의 MsgContext를 작성하는지 확인해야 합니다. 이를 통해 인바운드 형식과 일치하는 세션 데이터가 생성됩니다.

특정 플랫폼에서 세션 키가 일치하지 않나요?

• Slack: resolveThreadSessionKeys를 사용하여 replyTo 또는 threadId를 처리하세요.
• Discord: useSuffix=false 설정을 사용하여 인바운드 세션과 일치시키세요.
• Telegram: 토픽 ID가 chatId:topic:<id> 형식으로 매핑되는지 확인하세요.
• BlueBubbles: 그룹 타겟에서 chat_* 접두사가 제거되었는지 확인하세요.

Voice-call 플러그인 이슈

현재 Voice-call 플러그인은 voice:<phone>과 같은 커스텀 세션 키를 사용하며 아웃바운드 매핑이 표준화되어 있지 않습니다. message-tool에서 음성 전송을 지원해야 한다면 명시적인 매핑을 추가해야 합니다.

궁금한 점이 있다면 AI Setup Assistant에 문의해 주세요.

다음 단계

• Slack 스레드 세션 관리 가이드
• Gateway API 레퍼런스
• 플러그인 채널 라우팅 최적화