Copilot Manager IPC

2.1 호출자 플러그인 헤더

//@name my-plugin
//@api 3.0
//@allowed-ipc my-plugin copilot-manager

호출자 플러그인에도 //@allowed-ipc에 자신의 이름을 넣어야 합니다. (RisuAI v2026.4.181 버전까지 버그로 인해 allowed-ipc가 제대로 인식되지 않음)

2.2 Copilot Manager 측 허용 등록

RisuAI의 IPC는 양방향 허용이 필요합니다. Copilot Manager 플러그인 파일 상단의 //@allowed-ipc 선언에 여러분의 플러그인 이름을 추가해야 합니다.

- //@allowed-ipc copilot-manager provider-manager
+ //@allowed-ipc copilot-manager provider-manager my-plugin

양쪽 모두 선언되지 않으면 메시지가 전달되지 않습니다.

2.3 채널 이름

요청

interface IpcRequestEnvelope {
    id: string;        // 요청 고유 ID (호출자가 생성)
    op: "status" | "listModels" | "chat" | "cancel";
    payload?: unknown; // op별 데이터
}

응답

interface IpcResponseEnvelope {
    id: string;        // 요청의 id를 그대로 반영
    type: "status" | "models" | "accepted" | "chunk" | "done" | "error";
    data: unknown;     // type별 데이터
}

동일 id에 대해 여러 응답이 올 수 있습니다 (스트리밍: accepted → chunk × N → done).

5.1 status — 상태 + 쿼터 조회

페이로드 없음.

{
    configured: boolean,          // 토큰이 설정돼 있는가
    activeIndex: number,          // 현재 활성 키 인덱스
    keys: Array<{
        index: number,
        alias: string,            // 사용자 지정 별칭
        quota: {
            limit: number,        // -1이면 무제한 또는 조회 불가
            used: number
        }
    }>
}

const { data } = await callOnce("status");
if (!data.configured) console.warn("Copilot 토큰 미설정");

5.2 listModels — 모델 목록

페이로드 없음. 사용자가 숨긴 모델은 제외됩니다.

{ modelIds: string[] }  // 예: ["gpt-4.1", "claude-sonnet-4.7", ...]

5.3 chat — 추론 요청

interface ChatPayload {
    model_id: string;                 // 필수
    messages: IpcChatMessage[];       // 필수

    // Tool 사용 (§6 참조)
    tools?: ToolDefinition[];
    turn?: "auto" | "user" | "agent";
    chain_id?: string;

    // 샘플링 (모두 선택)
    temperature?: number;
    top_p?: number;
    top_k?: number;
    frequency_penalty?: number;
    presence_penalty?: number;
    max_tokens?: number;

    // Thinking / Reasoning (누락 시 전역 설정 상속)
    effort?: "" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    thinking_budget?: number;
    omit_thinking?: boolean;
    use_instructions?: boolean;
    detailed_summary?: boolean;
    verbosity?: "low" | "medium" | "high";

    // 라우팅
    format?: "auto" | "anthropic" | "responses" | "openai";

    // 전송 모드
    streaming?: boolean;              // 기본 false
    realtime_chunks?: boolean;        // 기본 false
    raw?: boolean;                    // 기본 false

    // 키 선택
    key_index?: number;               // 특정 키 사용
}

interface IpcChatMessage {
    role: "system" | "user" | "assistant" | "function" | "char" | "tool";
    content?: string;
    name?: string;
    tool_calls?: ToolCall[];          // assistant 메시지에 모델이 호출한 tool
    tool_call_id?: string;            // role="tool"에 필수
    is_error?: boolean;               // tool 실행 실패 표시
    multimodals?: Array<{
        type: "image" | "video" | "audio";
        base64: string;               // "data:image/png;base64,..." 형태
    }>;
    provider_contexts?: unknown[];    // 고급 용도
}

interface ToolCall {
    id: string;
    name: string;
    arguments: string;                // JSON 문자열 (검증 없이 보존됨)
}

interface ToolDefinition {
    name: string;
    description?: string;
    parameters?: Record<string, unknown>;
    strict?: boolean;
}

{ streaming, realtimeChunks, raw, turn, toolCount }

{ phase: "thinking" | "text" | "raw", text: string }

{
    success: true,
    content: string,              // realtime_chunks면 빈 문자열
    thinking?: string,
    toolCalls?: ToolCall[],       // 모델이 호출한 tool (§6)
    usage?: { inputTokens?, outputTokens?, thinkingTokens?, cachedInputTokens?, totalTokens? },
    durationMs?: number,
    stopReason?: string,
    providerContext?: unknown     // tool chain 연속성 (자동 관리됨)
}

{ code: string, message: string }

const result = await callOnce("chat", {
    model_id: "gpt-4.1",
    messages: [{ role: "user", content: "안녕하세요" }],
});
console.log(result.data.content);

function chatStream(modelId, text, onChunk) {
    return new Promise((resolve, reject) => {
        const id = send("chat", {
            model_id: modelId,
            messages: [{ role: "user", content: text }],
            streaming: true,
            realtime_chunks: true,
        });
        const timer = setTimeout(() => {
            pending.delete(id);
            reject(new Error("IPC timeout"));
        }, 120000);
        pending.set(id, (msg) => {
            if (msg.type === "accepted") return;
            if (msg.type === "chunk") {
                onChunk(msg.data);
                return;
            }
            clearTimeout(timer);
            pending.delete(id);
            if (msg.type === "error") reject(new Error(`[${msg.data.code}] ${msg.data.message}`));
            else resolve(msg.data);
        });
    });
}

let collected = "";
await chatStream("claude-sonnet-4.7", "5까지 세어줘", ({ phase, text }) => {
    if (phase === "text") collected += text;
});

5.4 cancel — 요청 취소

{ target_id: string }  // 취소할 chat 요청의 id

cancel 자체에 대한 성공 응답은 없습니다. 대상 chat이 CANCELLED 에러로 종료됩니다.

const chatId = send("chat", { model_id: "...", messages: [...], streaming: true, realtime_chunks: true });
// ... 나중에 취소
send("cancel", { target_id: chatId });

흐름

1. tools와 chain_id를 포함해 첫 요청 전송
2. done.toolCalls가 있으면 tool 실행
3. 결과를 role: "tool" 메시지로 포함해 같은 chain_id로 재요청
4. 모델이 최종 응답을 줄 때까지 반복

규칙

• tools를 싣거나 turn: "agent"를 보내는 경우 chain_id는 필수
• chain_id는 같은 체인 내 재사용 (envelope id는 매번 고유)
• turn: "auto"(기본)는 마지막 메시지가 tool이면 자동으로 agent 처리
• 체인 컨텍스트는 서버가 관리 — providerContext를 수동으로 넘길 필요 없음

예제

const chainId = `chain-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;

const tools = [{
    name: "get_weather",
    description: "Get weather for a city",
    parameters: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"],
    },
}];

// 1. 첫 요청
const first = await callOnce("chat", {
    model_id: "gpt-4.1",
    chain_id: chainId,
    tools,
    messages: [{ role: "user", content: "서울 날씨 알려줘" }],
});

if (first.data.toolCalls?.length) {
    // 2. Tool 실행
    const toolResults = await Promise.all(
        first.data.toolCalls.map(async (call) => {
            try {
                const result = await executeMyTool(call.name, call.arguments);
                return { role: "tool", tool_call_id: call.id, content: result };
            } catch (e) {
                return { role: "tool", tool_call_id: call.id, content: e.message, is_error: true };
            }
        }),
    );

    // 3. 결과 전송 (전체 대화 히스토리 재구성)
    const final = await callOnce("chat", {
        model_id: "gpt-4.1",
        chain_id: chainId,
        tools,
        messages: [
            { role: "user", content: "서울 날씨 알려줘" },
            { role: "assistant", content: first.data.content, tool_calls: first.data.toolCalls },
            ...toolResults,
        ],
    });
    console.log(final.data.content);
}