Instance, Connector, 복합 패키지

사용자별 실행 모델

Plugin package
  └─ Installation (사용자에게 설치된 패키지)
      └─ Default Instance (설치와 함께 유지되는 실행·설정 단위)
          ├─ Connection A (외부 계정)
          ├─ Connection B (외부 계정)
          └─ Child Instance (dependency가 있을 때만 내부 생성)

사용자가 같은 패키지를 여러 번 설치하거나 root Instance를 복제해 계정을 나누지 않습니다. 한 번의 설치로 default Instance 하나를 유지하고, 그 안에서 plugin_connections를 여러 개 관리합니다. settings, granted permissions, generation, storage namespace도 이 default Instance를 기준으로 실행됩니다.

여러 외부 계정

여러 Notion workspace나 여러 API 계정처럼 실제 서비스 계정을 추가하려면 Credential에 allow_multiple: true를 선언합니다. Host는 각 OAuth/API token 연결을 별도 Connection으로 저장하고, 실행할 때 선택한 connection_id를 사용합니다.

{
  "id": "workspace_account",
  "label": "Workspace 계정",
  "description": "검색할 workspace 연결",
  "kind": "oauth_access_token",
  "oauth_provider": "notion",
  "allow_multiple": true
}

allow_multiple: false이면 같은 default Instance와 credential 조합에 Connection 하나만 허용합니다. 이 제한은 다른 플러그인이나 dependency의 credential을 공유한다는 의미가 아닙니다.

Connector의 역할

Connector는 다음 외부 실행 정책을 한곳에 모읍니다.

• credential_id: 어떤 사용자 Connection을 쓸지
• cloud_connection_id: Developer Project의 OAuth provider 설정
• cloud_secret_id: 서버 측 Secret
• endpoint: 공개 HTTPS endpoint
• timeout_seconds, retry, rate_limit: 복구와 호출량 경계

Capability의 http_json 또는 mcp_http runtime은 connector_id를 참조합니다. endpoint나 credential을 runtime에도 중복 선언하면 값이 Connector와 정확히 일치해야 합니다. 가능한 한 Connector 한곳에만 둡니다.

Dependency와 Child Instance

dependencies가 있는 복합 패키지는 Host가 child package를 검증·설치한 뒤 내부 Child Instance를 만듭니다. Child Instance는 사용자가 같은 플러그인 계정을 하나 더 추가하는 기능이 아닙니다.

• 부모는 dependency의 exposed_capabilities만 호출합니다.
• 부모와 자식의 settings, credential, storage, generation은 분리됩니다.
• 부모 삭제 또는 dependency 변경 시 해당 관계의 Child Instance를 정리합니다.
• 동일 child package를 다른 부모가 사용해도 실행 상태를 공유하지 않습니다.

{
  "id": "core",
  "plugin_id": "com.example.core",
  "required": true,
  "package_path": "children/core.mplg",
  "exposed_capabilities": ["com.example.core.search"]
}

부모 capability는 다음처럼 호출합니다.

{
  "adapter": "child_plugin",
  "dependency_id": "core",
  "capability": "com.example.core.search"
}

선택 기준

계정 선택 UI는 계정의 표시 이름과 연결 상태를 보여주고 token·secret 자체는 표시하지 않습니다. 연결 만료는 기능 오류와 구분해 “다시 연결” 동작을 제공해야 합니다.